Generate HTML documentation

[github/shaarli/Shaarli.git] / doc / html / mkdocs / search_index.json

{
    "docs": [
        {
            "location": "/",
            "text": "Shaarli\n documentation\n\n\nHere you can find some info on how to use, configure, tweak and solve problems with your Shaarli.\n\n\nFor general info, read the \nREADME\n.\n\n\nIf you have any questions or ideas, please join the \nchat\n (also reachable via \nIRC\n), post them in our \ngeneral discussion\n or read the current \nissues\n.\nIf you've found a bug, please create a \nnew issue\n.\n\n\nIf you would like a feature added to Shaarli, check the issues labeled \nfeature\n, \nenhancement\n, and \nplugin\n.\n\n\nNote: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the \ndoc/html/\n directory of your Shaarli installation.\n\n\n\n\n\n\n\n\nDemo\n\n\nYou can use this \npublic demo instance of Shaarli\n.\nIt runs the latest development version of Shaarli and is updated/reset daily.\n\n\nLogin: \ndemo\n; Password: \ndemo\n\n\nFeatures\n\n\nInterface\n\n\n\n\nminimalist design (simple is beautiful)\n\n\nFAST\n\n\nATOM and RSS feeds\n\n\nviews:\n\n\npaginated link list\n\n\ntag cloud\n\n\npicture wall: image and video thumbnails\n\n\ndaily: newspaper-like daily digest\n\n\ndaily RSS feed\n\n\n\n\n\n\npermalinks for easy reference\n\n\nlinks can be public or private\n\n\nextensible through \nplugins\n\n\n\n\nTag, view and search your links!\n\n\n\n\nadd a custom title and description to archived links\n\n\nadd tags to classify and search links\n\n\nfeatures tag autocompletion, renaming, merging and deletion\n\n\n\n\n\n\nfull-text and tag search\n\n\n\n\nEasy setup\n\n\n\n\ndead-simple installation: drop the files, open the page\n\n\nlinks are stored in a file\n\n\ncompact storage\n\n\nno database required\n\n\neasy backup: simply copy the datastore file\n\n\n\n\n\n\nimport and export links as Netscape bookmarks\n\n\n\n\nAccessibility\n\n\n\n\nFirefox bookmarlet to share links in one click\n\n\nsupport for mobile browsers\n\n\nworks with Javascript disabled\n\n\neasy page customization through HTML/CSS/RainTPL\n\n\n\n\nSecurity\n\n\n\n\nbruteforce-proof login form\n\n\nprotected against \nXSRF\n\nand session cookie hijacking\n\n\n\n\nGoodies\n\n\n\n\nthumbnail generation for images and video services:\ndailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...\n\n\nlazy-loading with \nbLazy\n\n\n\n\n\n\nPubSubHubbub\n protocol support\n\n\nURL cleanup: automatic removal of \n?utm_source=...\n, \nfb=...\n\n\ndiscreet pop-up notification when a new release is available\n\n\n\n\nREST API\n\n\nEasily extensible by any client using the REST API exposed by Shaarli.\n\n\nSee the \nAPI documentation\n.\n\n\nOther usages\n\n\nThough Shaarli is primarily a bookmarking application, it can serve other purposes\n(see \nusage examples\n):\n- micro-blogging\n- pastebin\n- online notepad\n- snippet archive\n\n\nAbout\n\n\nShaarli community fork\n\n\nThis friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli\n\n\nThis is a community fork of the original \nShaarli\n project by \nS\u00e9bastien Sauvage\n.\n\n\nThe original project is currently unmaintained, and the developer \nhas informed us\n\nthat he would have no time to work on Shaarli in the near future.\nThe Shaarli community has carried on the work to provide\n\nmany patches\n\nfor \nbug fixes and enhancements\n\nin this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.\n\n\nContributing\n\n\nIf you'd like to help, please:\n- have a look at the open \nissues\n\nand \npull requests\n\n- feel free to report bugs (feedback is much appreciated)\n- suggest new features and improvements to both code and \ndocumentation\n\n- propose solutions to existing problems\n- submit pull requests :-)\n\n\nLicense\n\n\nShaarli is \nFree Software\n. See \nCOPYING\n for a detail of the contributors and licenses for each individual component.",
            "title": "Home"
        },
        {
            "location": "/#shaarli-documentation",
            "text": "Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.  For general info, read the  README .  If you have any questions or ideas, please join the  chat  (also reachable via  IRC ), post them in our  general discussion  or read the current  issues .\nIf you've found a bug, please create a  new issue .  If you would like a feature added to Shaarli, check the issues labeled  feature ,  enhancement , and  plugin .  Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the  doc/html/  directory of your Shaarli installation.",
            "title": "Shaarli documentation"
        },
        {
            "location": "/#demo",
            "text": "You can use this  public demo instance of Shaarli .\nIt runs the latest development version of Shaarli and is updated/reset daily.  Login:  demo ; Password:  demo",
            "title": "Demo"
        },
        {
            "location": "/#features",
            "text": "",
            "title": "Features"
        },
        {
            "location": "/#interface",
            "text": "minimalist design (simple is beautiful)  FAST  ATOM and RSS feeds  views:  paginated link list  tag cloud  picture wall: image and video thumbnails  daily: newspaper-like daily digest  daily RSS feed    permalinks for easy reference  links can be public or private  extensible through  plugins",
            "title": "Interface"
        },
        {
            "location": "/#tag-view-and-search-your-links",
            "text": "add a custom title and description to archived links  add tags to classify and search links  features tag autocompletion, renaming, merging and deletion    full-text and tag search",
            "title": "Tag, view and search your links!"
        },
        {
            "location": "/#easy-setup",
            "text": "dead-simple installation: drop the files, open the page  links are stored in a file  compact storage  no database required  easy backup: simply copy the datastore file    import and export links as Netscape bookmarks",
            "title": "Easy setup"
        },
        {
            "location": "/#accessibility",
            "text": "Firefox bookmarlet to share links in one click  support for mobile browsers  works with Javascript disabled  easy page customization through HTML/CSS/RainTPL",
            "title": "Accessibility"
        },
        {
            "location": "/#security",
            "text": "bruteforce-proof login form  protected against  XSRF \nand session cookie hijacking",
            "title": "Security"
        },
        {
            "location": "/#goodies",
            "text": "thumbnail generation for images and video services:\ndailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...  lazy-loading with  bLazy    PubSubHubbub  protocol support  URL cleanup: automatic removal of  ?utm_source=... ,  fb=...  discreet pop-up notification when a new release is available",
            "title": "Goodies"
        },
        {
            "location": "/#rest-api",
            "text": "Easily extensible by any client using the REST API exposed by Shaarli.  See the  API documentation .",
            "title": "REST API"
        },
        {
            "location": "/#other-usages",
            "text": "Though Shaarli is primarily a bookmarking application, it can serve other purposes\n(see  usage examples ):\n- micro-blogging\n- pastebin\n- online notepad\n- snippet archive",
            "title": "Other usages"
        },
        {
            "location": "/#about",
            "text": "",
            "title": "About"
        },
        {
            "location": "/#shaarli-community-fork",
            "text": "This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli  This is a community fork of the original  Shaarli  project by  S\u00e9bastien Sauvage .  The original project is currently unmaintained, and the developer  has informed us \nthat he would have no time to work on Shaarli in the near future.\nThe Shaarli community has carried on the work to provide many patches \nfor  bug fixes and enhancements \nin this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.",
            "title": "Shaarli community fork"
        },
        {
            "location": "/#contributing",
            "text": "If you'd like to help, please:\n- have a look at the open  issues \nand  pull requests \n- feel free to report bugs (feedback is much appreciated)\n- suggest new features and improvements to both code and  documentation \n- propose solutions to existing problems\n- submit pull requests :-)",
            "title": "Contributing"
        },
        {
            "location": "/#license",
            "text": "Shaarli is  Free Software . See  COPYING  for a detail of the contributors and licenses for each individual component.",
            "title": "License"
        },
        {
            "location": "/Download-and-Installation/",
            "text": "To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your \nserver\n is properly \nconfigured\n.\n\n\nSeveral releases are available:\n\n\n\n\nLatest release (recommended)\n\n\nDownload as an archive\n\n\nGet the latest released version from the \nreleases\n page.\n\n\nDownload our \nshaarli-full\n archive\n to include dependencies.\n\n\nThe current latest released version is \nv0.8.4\n\n\nOr in command lines:\n\n\n$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip\n$ unzip shaarli-v0.8.4-full.zip\n$ mv Shaarli /path/to/shaarli/\n\n\n\n\n\n\n\n\n\n\n!\n\n\nIn most cases, download Shaarli from the \nreleases\n page. Cloning using \ngit\n or downloading Github branches as zip files requires additional steps (see below).\n\n\n\n\n\n\n\n\n\n\nUsing git\n\n\nmkdir -p /path/to/shaarli && cd /path/to/shaarli/\ngit clone -b v0.8 https://github.com/shaarli/Shaarli.git .\ncomposer install --no-dev\n\n\n\n\n\n\nStable version\n\n\nThe stable version has been experienced by Shaarli users, and will receive security updates.\n\n\nDownload as an archive\n\n\nAs a .zip archive:\n\n\n$ wget https://github.com/shaarli/Shaarli/archive/stable.zip\n$ unzip stable.zip\n$ mv Shaarli-stable /path/to/shaarli/\n\n\n\n\nAs a .tar.gz archive :\n\n\n$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz\n$ tar xvf stable.tar.gz\n$ mv Shaarli-stable /path/to/shaarli/\n\n\n\n\nClone with Git\n\n\nComposer\n is required to build a functional Shaarli installation when pulling from git.\n\n\n$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli/\n$ composer install --no-dev\n\n\n\n\n\n\nDevelopment version (mainline)\n\n\nUse at your own risk!\n\n\nTo get the latest changes from the \nmaster\n branch:\n\n\n# clone the repository  \n$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli\n$ composer install --no-dev\n\n\n\n\n\n\nFinish Installation\n\n\nOnce Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.\n\n\n\n\nSetup your Shaarli installation, and it's ready to use!\n\n\n\n\nUpdating Shaarli\n\n\nSee \nUpgrade and Migration",
            "title": "Download and Installation"
        },
        {
            "location": "/Download-and-Installation/#latest-release-recommended",
            "text": "",
            "title": "Latest release (recommended)"
        },
        {
            "location": "/Download-and-Installation/#download-as-an-archive",
            "text": "Get the latest released version from the  releases  page.  Download our  shaarli-full  archive  to include dependencies.  The current latest released version is  v0.8.4  Or in command lines:  $ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip\n$ unzip shaarli-v0.8.4-full.zip\n$ mv Shaarli /path/to/shaarli/     !  In most cases, download Shaarli from the  releases  page. Cloning using  git  or downloading Github branches as zip files requires additional steps (see below).",
            "title": "Download as an archive"
        },
        {
            "location": "/Download-and-Installation/#using-git",
            "text": "mkdir -p /path/to/shaarli && cd /path/to/shaarli/\ngit clone -b v0.8 https://github.com/shaarli/Shaarli.git .\ncomposer install --no-dev",
            "title": "Using git"
        },
        {
            "location": "/Download-and-Installation/#stable-version",
            "text": "The stable version has been experienced by Shaarli users, and will receive security updates.",
            "title": "Stable version"
        },
        {
            "location": "/Download-and-Installation/#download-as-an-archive_1",
            "text": "As a .zip archive:  $ wget https://github.com/shaarli/Shaarli/archive/stable.zip\n$ unzip stable.zip\n$ mv Shaarli-stable /path/to/shaarli/  As a .tar.gz archive :  $ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz\n$ tar xvf stable.tar.gz\n$ mv Shaarli-stable /path/to/shaarli/",
            "title": "Download as an archive"
        },
        {
            "location": "/Download-and-Installation/#clone-with-git",
            "text": "Composer  is required to build a functional Shaarli installation when pulling from git.  $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli/\n$ composer install --no-dev",
            "title": "Clone with Git"
        },
        {
            "location": "/Download-and-Installation/#development-version-mainline",
            "text": "Use at your own risk!  To get the latest changes from the  master  branch:  # clone the repository  \n$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli\n$ composer install --no-dev",
            "title": "Development version (mainline)"
        },
        {
            "location": "/Download-and-Installation/#finish-installation",
            "text": "Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.   Setup your Shaarli installation, and it's ready to use!",
            "title": "Finish Installation"
        },
        {
            "location": "/Download-and-Installation/#updating-shaarli",
            "text": "See  Upgrade and Migration",
            "title": "Updating Shaarli"
        },
        {
            "location": "/Upgrade-and-migration/",
            "text": "Preparation\n\n\nNote your current version\n\n\nIf anything goes wrong, it's important for us to know which version you're upgrading from.\n\nThe current version is present in the \nversion.php\n file.\n\n\nBackup your data\n\n\nShaarli stores all user data under the \ndata\n directory:\n- \ndata/config.php\n - main configuration file\n- \ndata/datastore.php\n - bookmarked links\n- \ndata/ipbans.php\n - banned IP addresses\n- \ndata/updates.txt\n - contains all automatic update to the configuration and datastore files already run\n\n\nSee \nShaarli configuration\n for more information about Shaarli resources.\n\n\nIt is recommended to backup this repository \nbefore\n starting updating/upgrading Shaarli:\n- users with SSH access: copy or archive the directory to a temporary location\n- users with FTP access: download a local copy of your Shaarli installation using your favourite client\n\n\nMigrating data from a previous installation\n\n\nAs all user data is kept under \ndata\n, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:\n\n\n\n\nbackup the \ndata\n directory\n\n\ninstall or update Shaarli:\n\n\nfresh installation - see \nDownload and installation\n\n\nupdate - see the following sections\n\n\n\n\n\n\ncheck or restore the \ndata\n directory\n\n\n\n\nRecommended : Upgrading from release archives\n\n\nAll tagged revisions can be downloaded as tarballs or ZIP archives from the \nreleases\n page.\n\n\nWe recommend that you use the latest release tarball with the \n-full\n suffix. It contains the dependencies, please read \nDownload and installation\n for \ngit\n complete instructions.\n\n\nOnce downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the \ndata\n directory!\n\n\nAfter upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to \ndata/config.json.php\n (see \nShaarli configuration\n for more details).\n\n\nUpgrading with Git\n\n\nUpdating a community Shaarli\n\n\nIf you have installed Shaarli from the \ncommunity Git repository\n, simply \npull new changes\n from your local clone:\n\n\n$ cd /path/to/shaarli\n$ git pull\n\nFrom github.com:shaarli/Shaarli\n * branch            master     -> FETCH_HEAD\nUpdating ebd67c6..521f0e6\nFast-forward\n application/Url.php   | 1 +\n shaarli_version.php   | 2 +-\n tests/Url/UrlTest.php | 1 +\n 3 files changed, 3 insertions(+), 1 deletion(-)\n\n\n\n\nShaarli >= \nv0.8.x\n: install/update third-party PHP dependencies using \nComposer\n:\n\n\n$ composer install --no-dev\n\nLoading composer repositories with package information\nUpdating dependencies\n  - Installing shaarli/netscape-bookmark-parser (v1.0.1)\n    Downloading: 100%\n\n\n\n\nMigrating and upgrading from Sebsauvage's repository\n\n\nIf you have installed Shaarli from \nSebsauvage's original Git repository\n, you can use \nGit remotes\n to update your working copy.\n\n\nThe following guide assumes that:\n- you have a basic knowledge of Git \nbranching\n and \nremote repositories\n\n- the default remote is named \norigin\n and points to Sebsauvage's repository\n- the current branch is \nmaster\n\n    - if you have personal branches containing customizations, you will need to \nrebase them\n after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!\n- the working copy is clean:\n    - no versioned file has been locally modified\n    - no untracked files are present\n\n\nStep 0: show repository information\n\n\n$ cd /path/to/shaarli\n\n$ git remote -v\norigin  https://github.com/sebsauvage/Shaarli (fetch)\norigin  https://github.com/sebsauvage/Shaarli (push)\n\n$ git branch -vv\n* master 029f75f [origin/master] Update README.md\n\n$ git status\nOn branch master\nYour branch is up-to-date with 'origin/master'.\nnothing to commit, working directory clean\n\n\n\n\nStep 1: update Git remotes\n\n\n$ git remote rename origin sebsauvage\n$ git remote -v\nsebsauvage  https://github.com/sebsauvage/Shaarli (fetch)\nsebsauvage  https://github.com/sebsauvage/Shaarli (push)\n\n$ git remote add origin https://github.com/shaarli/Shaarli\n$ git fetch origin\n\nremote: Counting objects: 3015, done.\nremote: Compressing objects: 100% (19/19), done.\nremote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550\nReceiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.\nResolving deltas: 100% (1899/1899), completed with 48 local objects.\nFrom https://github.com/shaarli/Shaarli\n * [new branch]      master     -> origin/master\n * [new branch]      stable     -> origin/stable\n[...]\n * [new tag]         v0.6.4     -> v0.6.4\n * [new tag]         v0.7.0     -> v0.7.0\n\n\n\n\nStep 2: use the stable community branch\n\n\n$ git checkout origin/stable -b stable\nBranch stable set up to track remote branch stable from origin.\nSwitched to a new branch 'stable'\n\n$ git branch -vv\n  master 029f75f [sebsauvage/master] Update README.md\n* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5\n\n\n\n\nShaarli >= \nv0.8.x\n: install/update third-party PHP dependencies using \nComposer\n:\n\n\n$ composer install --no-dev\n\nLoading composer repositories with package information\nUpdating dependencies\n  - Installing shaarli/netscape-bookmark-parser (v1.0.1)\n    Downloading: 100%\n\n\n\n\nOptionally, you can delete information related to the legacy version:\n\n\n$ git branch -D master\nDeleted branch master (was 029f75f).\n\n$ git remote remove sebsauvage\n\n$ git remote -v\norigin  https://github.com/shaarli/Shaarli (fetch)\norigin  https://github.com/shaarli/Shaarli (push)\n\n$ git gc\nCounting objects: 3317, done.\nDelta compression using up to 8 threads.\nCompressing objects: 100% (1237/1237), done.\nWriting objects: 100% (3317/3317), done.\nTotal 3317 (delta 2050), reused 3301 (delta 2034)to\n\n\n\n\nStep 3: configuration\n\n\nAfter migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to \ndata/config.php\n (see \nShaarli configuration\n for more details).\n\n\nTroubleshooting\n\n\nIf the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.\n\n\nYou must specify an integer as a key\n\n\nIn \nv0.8.1\n we changed how link keys are handled (from timestamps to incremental integers).\nTake a look at \ndata/updates.txt\n content.\n\n\nupdates.txt\n contains \nupdateMethodDatastoreIds\n\n\nTry to delete it and refresh your page while being logged in.\n\n\nupdates.txt\n doesn't exists or doesn't contain \nupdateMethodDatastoreIds\n\n\n\n\nCreate \ndata/updates.txt\n if it doesn't exist.\n\n\nPaste this string in the update file \n;updateMethodRenameDashTags;\n\n\nLogin to Shaarli.\n\n\nDelete the update file.\n\n\nRefresh.",
            "title": "Upgrade and migration"
        },
        {
            "location": "/Upgrade-and-migration/#preparation",
            "text": "",
            "title": "Preparation"
        },
        {
            "location": "/Upgrade-and-migration/#note-your-current-version",
            "text": "If anything goes wrong, it's important for us to know which version you're upgrading from. \nThe current version is present in the  version.php  file.",
            "title": "Note your current version"
        },
        {
            "location": "/Upgrade-and-migration/#backup-your-data",
            "text": "Shaarli stores all user data under the  data  directory:\n-  data/config.php  - main configuration file\n-  data/datastore.php  - bookmarked links\n-  data/ipbans.php  - banned IP addresses\n-  data/updates.txt  - contains all automatic update to the configuration and datastore files already run  See  Shaarli configuration  for more information about Shaarli resources.  It is recommended to backup this repository  before  starting updating/upgrading Shaarli:\n- users with SSH access: copy or archive the directory to a temporary location\n- users with FTP access: download a local copy of your Shaarli installation using your favourite client",
            "title": "Backup your data"
        },
        {
            "location": "/Upgrade-and-migration/#migrating-data-from-a-previous-installation",
            "text": "As all user data is kept under  data , this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:   backup the  data  directory  install or update Shaarli:  fresh installation - see  Download and installation  update - see the following sections    check or restore the  data  directory",
            "title": "Migrating data from a previous installation"
        },
        {
            "location": "/Upgrade-and-migration/#recommended-upgrading-from-release-archives",
            "text": "All tagged revisions can be downloaded as tarballs or ZIP archives from the  releases  page.  We recommend that you use the latest release tarball with the  -full  suffix. It contains the dependencies, please read  Download and installation  for  git  complete instructions.  Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the  data  directory!  After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to  data/config.json.php  (see  Shaarli configuration  for more details).",
            "title": "Recommended : Upgrading from release archives"
        },
        {
            "location": "/Upgrade-and-migration/#upgrading-with-git",
            "text": "",
            "title": "Upgrading with Git"
        },
        {
            "location": "/Upgrade-and-migration/#updating-a-community-shaarli",
            "text": "If you have installed Shaarli from the  community Git repository , simply  pull new changes  from your local clone:  $ cd /path/to/shaarli\n$ git pull\n\nFrom github.com:shaarli/Shaarli\n * branch            master     -> FETCH_HEAD\nUpdating ebd67c6..521f0e6\nFast-forward\n application/Url.php   | 1 +\n shaarli_version.php   | 2 +-\n tests/Url/UrlTest.php | 1 +\n 3 files changed, 3 insertions(+), 1 deletion(-)  Shaarli >=  v0.8.x : install/update third-party PHP dependencies using  Composer :  $ composer install --no-dev\n\nLoading composer repositories with package information\nUpdating dependencies\n  - Installing shaarli/netscape-bookmark-parser (v1.0.1)\n    Downloading: 100%",
            "title": "Updating a community Shaarli"
        },
        {
            "location": "/Upgrade-and-migration/#migrating-and-upgrading-from-sebsauvages-repository",
            "text": "If you have installed Shaarli from  Sebsauvage's original Git repository , you can use  Git remotes  to update your working copy.  The following guide assumes that:\n- you have a basic knowledge of Git  branching  and  remote repositories \n- the default remote is named  origin  and points to Sebsauvage's repository\n- the current branch is  master \n    - if you have personal branches containing customizations, you will need to  rebase them  after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!\n- the working copy is clean:\n    - no versioned file has been locally modified\n    - no untracked files are present",
            "title": "Migrating and upgrading from Sebsauvage's repository"
        },
        {
            "location": "/Upgrade-and-migration/#step-0-show-repository-information",
            "text": "$ cd /path/to/shaarli\n\n$ git remote -v\norigin  https://github.com/sebsauvage/Shaarli (fetch)\norigin  https://github.com/sebsauvage/Shaarli (push)\n\n$ git branch -vv\n* master 029f75f [origin/master] Update README.md\n\n$ git status\nOn branch master\nYour branch is up-to-date with 'origin/master'.\nnothing to commit, working directory clean",
            "title": "Step 0: show repository information"
        },
        {
            "location": "/Upgrade-and-migration/#step-1-update-git-remotes",
            "text": "$ git remote rename origin sebsauvage\n$ git remote -v\nsebsauvage  https://github.com/sebsauvage/Shaarli (fetch)\nsebsauvage  https://github.com/sebsauvage/Shaarli (push)\n\n$ git remote add origin https://github.com/shaarli/Shaarli\n$ git fetch origin\n\nremote: Counting objects: 3015, done.\nremote: Compressing objects: 100% (19/19), done.\nremote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550\nReceiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.\nResolving deltas: 100% (1899/1899), completed with 48 local objects.\nFrom https://github.com/shaarli/Shaarli\n * [new branch]      master     -> origin/master\n * [new branch]      stable     -> origin/stable\n[...]\n * [new tag]         v0.6.4     -> v0.6.4\n * [new tag]         v0.7.0     -> v0.7.0",
            "title": "Step 1: update Git remotes"
        },
        {
            "location": "/Upgrade-and-migration/#step-2-use-the-stable-community-branch",
            "text": "$ git checkout origin/stable -b stable\nBranch stable set up to track remote branch stable from origin.\nSwitched to a new branch 'stable'\n\n$ git branch -vv\n  master 029f75f [sebsauvage/master] Update README.md\n* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5  Shaarli >=  v0.8.x : install/update third-party PHP dependencies using  Composer :  $ composer install --no-dev\n\nLoading composer repositories with package information\nUpdating dependencies\n  - Installing shaarli/netscape-bookmark-parser (v1.0.1)\n    Downloading: 100%  Optionally, you can delete information related to the legacy version:  $ git branch -D master\nDeleted branch master (was 029f75f).\n\n$ git remote remove sebsauvage\n\n$ git remote -v\norigin  https://github.com/shaarli/Shaarli (fetch)\norigin  https://github.com/shaarli/Shaarli (push)\n\n$ git gc\nCounting objects: 3317, done.\nDelta compression using up to 8 threads.\nCompressing objects: 100% (1237/1237), done.\nWriting objects: 100% (3317/3317), done.\nTotal 3317 (delta 2050), reused 3301 (delta 2034)to",
            "title": "Step 2: use the stable community branch"
        },
        {
            "location": "/Upgrade-and-migration/#step-3-configuration",
            "text": "After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to  data/config.php  (see  Shaarli configuration  for more details).",
            "title": "Step 3: configuration"
        },
        {
            "location": "/Upgrade-and-migration/#troubleshooting",
            "text": "If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.",
            "title": "Troubleshooting"
        },
        {
            "location": "/Upgrade-and-migration/#you-must-specify-an-integer-as-a-key",
            "text": "In  v0.8.1  we changed how link keys are handled (from timestamps to incremental integers).\nTake a look at  data/updates.txt  content.",
            "title": "You must specify an integer as a key"
        },
        {
            "location": "/Upgrade-and-migration/#updatestxt-contains-updatemethoddatastoreids",
            "text": "Try to delete it and refresh your page while being logged in.",
            "title": "updates.txt contains updateMethodDatastoreIds"
        },
        {
            "location": "/Upgrade-and-migration/#updatestxt-doesnt-exists-or-doesnt-contain-updatemethoddatastoreids",
            "text": "Create  data/updates.txt  if it doesn't exist.  Paste this string in the update file  ;updateMethodRenameDashTags;  Login to Shaarli.  Delete the update file.  Refresh.",
            "title": "updates.txt doesn't exists or doesn't contain updateMethodDatastoreIds"
        },
        {
            "location": "/Server-requirements/",
            "text": "PHP\n\n\nRelease information\n\n\n\n\nPHP: Supported versions\n\n\nPHP: Unsupported versions\n \n(EOL - End Of Life)\n\n\nPHP 7 Changelog\n\n\nPHP 5 Changelog\n\n\nPHP: Bugs\n\n\n\n\nSupported versions\n\n\n\n\n\n\n\n\nVersion\n\n\nStatus\n\n\nShaarli compatibility\n\n\n\n\n\n\n\n\n\n\n7.1\n\n\nSupported (v0.9.x)\n\n\n:white_check_mark:\n\n\n\n\n\n\n7.0\n\n\nSupported\n\n\n:white_check_mark:\n\n\n\n\n\n\n5.6\n\n\nSupported\n\n\n:white_check_mark:\n\n\n\n\n\n\n5.5\n\n\nEOL: 2016-07-10\n\n\n:white_check_mark:\n\n\n\n\n\n\n5.4\n\n\nEOL: 2015-09-14\n\n\n:white_check_mark: (up to Shaarli 0.8.x)\n\n\n\n\n\n\n5.3\n\n\nEOL: 2014-08-14\n\n\n:white_check_mark: (up to Shaarli 0.8.x)\n\n\n\n\n\n\n\n\nSee also:\n- \nTravis configuration\n\n\nDependency management\n\n\nStarting with Shaarli \nv0.8.x\n, \nComposer\n is used to resolve,\ndownload and install third-party PHP dependencies.\n\n\n\n\n\n\n\n\nLibrary\n\n\nRequired?\n\n\nUsage\n\n\n\n\n\n\n\n\n\n\nshaarli/netscape-bookmark-parser\n\n\nAll\n\n\nImport bookmarks from Netscape files\n\n\n\n\n\n\nerusev/parsedown\n\n\nAll\n\n\nParse MarkDown syntax for the MarkDown plugin\n\n\n\n\n\n\nslim/slim\n\n\nAll\n\n\nHandle routes and middleware for the REST API\n\n\n\n\n\n\n\n\nExtensions\n\n\n\n\n\n\n\n\nExtension\n\n\nRequired?\n\n\nUsage\n\n\n\n\n\n\n\n\n\n\nopenssl\n\n\nAll\n\n\nOpenSSL, HTTPS\n\n\n\n\n\n\nphp-mbstring\n\n\nCentOS, Fedora, RHEL, Windows\n\n\nmultibyte (Unicode) string support\n\n\n\n\n\n\nphp-gd\n\n\noptional\n\n\nthumbnail resizing\n\n\n\n\n\n\nphp-intl\n\n\noptional\n\n\nlocalized text sorting (e.g. \ne->\u00e8->f\n)\n\n\n\n\n\n\nphp-curl\n\n\noptional\n\n\nusing cURL for fetching webpages and thumbnails in a more robust way",
            "title": "Server requirements"
        },
        {
            "location": "/Server-requirements/#php",
            "text": "",
            "title": "PHP"
        },
        {
            "location": "/Server-requirements/#release-information",
            "text": "PHP: Supported versions  PHP: Unsupported versions   (EOL - End Of Life)  PHP 7 Changelog  PHP 5 Changelog  PHP: Bugs",
            "title": "Release information"
        },
        {
            "location": "/Server-requirements/#supported-versions",
            "text": "Version  Status  Shaarli compatibility      7.1  Supported (v0.9.x)  :white_check_mark:    7.0  Supported  :white_check_mark:    5.6  Supported  :white_check_mark:    5.5  EOL: 2016-07-10  :white_check_mark:    5.4  EOL: 2015-09-14  :white_check_mark: (up to Shaarli 0.8.x)    5.3  EOL: 2014-08-14  :white_check_mark: (up to Shaarli 0.8.x)     See also:\n-  Travis configuration",
            "title": "Supported versions"
        },
        {
            "location": "/Server-requirements/#dependency-management",
            "text": "Starting with Shaarli  v0.8.x ,  Composer  is used to resolve,\ndownload and install third-party PHP dependencies.     Library  Required?  Usage      shaarli/netscape-bookmark-parser  All  Import bookmarks from Netscape files    erusev/parsedown  All  Parse MarkDown syntax for the MarkDown plugin    slim/slim  All  Handle routes and middleware for the REST API",
            "title": "Dependency management"
        },
        {
            "location": "/Server-requirements/#extensions",
            "text": "Extension  Required?  Usage      openssl  All  OpenSSL, HTTPS    php-mbstring  CentOS, Fedora, RHEL, Windows  multibyte (Unicode) string support    php-gd  optional  thumbnail resizing    php-intl  optional  localized text sorting (e.g.  e->\u00e8->f )    php-curl  optional  using cURL for fetching webpages and thumbnails in a more robust way",
            "title": "Extensions"
        },
        {
            "location": "/Server-configuration/",
            "text": "Example virtual host configurations for popular web servers\n\n\n\n\nApache\n\n\nNginx\n\n\n\n\nPrerequisites\n\n\nShaarli\n\n\n\n\nShaarli is installed in a directory readable/writeable by the user\n\n\nthe correct read/write permissions have been granted to the web server \nuser and/or group\n\n\nfor HTTPS / SSL:\n\n\na key pair (public, private) and a certificate have been generated\n\n\nthe appropriate server SSL extension is installed and active\n\n\n\n\nHTTPS, TLS and self-signed certificates\n\n\nRelated guides:\n\n \nHow to Create Self-Signed SSL Certificates with OpenSSL\n\n\n \nHow do I create my own Certificate Authority?\n\n* Generate a self-signed certificate (will trigger browser warnings) with apache2: \nmake-ssl-cert generate-default-snakeoil --force-overwrite\n will create \n/etc/ssl/certs/ssl-cert-snakeoil.pem\n and \n/etc/ssl/private/ssl-cert-snakeoil.key\n\n\nProxies\n\n\nIf Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:\n- \nX-Forwarded-Proto\n;\n- \nX-Forwarded-Host\n;\n- \nX-Forwarded-For\n.\n\n\nSee also \nproxy-related\n issues.\n\n\nApache\n\n\nMinimal\n\n\n<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n</VirtualHost>\n\n\n\n\nDebug - Log all the things!\n\n\nThis configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.\n\n\nSee:\n\n \nApache/PHP - error log per VirtualHost\n (StackOverflow)\n\n \nPHP: php_value vs php_admin_value and the use of php_flag explained\n\n\n<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n\n    php_flag  log_errors on\n    php_flag  display_errors on\n    php_value error_reporting 2147483647\n    php_value error_log /var/log/apache2/shaarli-php-error.log\n</VirtualHost>\n\n\n\n\nStandard - Keep access and error logs\n\n\n<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>\n\n\n\n\nParanoid - Redirect HTTP (:80) to HTTPS (:443)\n\n\nSee \nServer-side TLS\n (Mozilla).\n\n\n<VirtualHost *:443>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    SSLEngine             on\n    SSLCertificateFile    /absolute/path/to/the/website/certificate.pem\n    SSLCertificateKeyFile /absolute/path/to/the/website/key.key\n\n    <Directory /absolute/path/to/shaarli/>\n        AllowOverride All\n        Options Indexes FollowSymLinks MultiViews\n        Order allow,deny\n        allow from all\n    </Directory>\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>\n<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    Redirect 301 / https://shaarli.my-domain.org\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>\n\n\n\n\n.htaccess\n\n\nShaarli use \n.htaccess\n Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive \nAllowOverride All\n in your virtual host configuration for them to work.\n\n\nWarning\n: If you use Apache 2.2 or lower, you need \nmod_version\n to be installed and enabled.\n\n\nApache module \nmod_rewrite\n \nmust\n be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root \n.htaccess\n file.\n\n\nLightHttpd\n\n\nNginx\n\n\nForeword\n\n\nNginx does not natively interpret PHP scripts; to this effect, we will run a \nFastCGI\n service, to which Nginx's FastCGI module will proxy all requests to PHP resources.\n\n\nRequired packages:\n- \nnginx\n\n- \nphp-fpm\n - PHP FastCGI Process Manager\n\n\nOfficial documentation:\n- \nBeginner's guide\n\n- \nngx_http_fastcgi_module\n\n- \nPitfalls\n\n\nCommunity resources:\n- \nServer-side TLS (Nginx)\n (Mozilla)\n- \nPHP configuration examples\n (Karl Blessing)\n\n\nCommon setup\n\n\nOnce Nginx and PHP-FPM are installed, we need to ensure:\n- Nginx and PHP-FPM are running using the \nsame user and group\n\n- both these user and group have\n    - \nread\n permissions for Shaarli resources\n    - \nexecute\n permissions for Shaarli directories \nAND\n their parent directories\n\n\nOn a production server:\n- \nuser:group\n will likely be \nhttp:http\n, \nwww:www\n or \nwww-data:www-data\n\n- files will be located under \n/var/www\n, \n/var/http\n or \n/usr/share/nginx\n\n\nOn a development server:\n- files may be located in a user's home directory\n- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!\n\n\nFor all following configuration examples, this user/group pair will be used:\n- \nuser:group = john:users\n,\n\n\nwhich corresponds to the following service configuration:\n\n\n; /etc/php/php-fpm.conf\nuser = john\ngroup = users\n\n[...]\nlisten.owner = john\nlisten.group = users\n\n\n\n\n# /etc/nginx/nginx.conf\nuser john users;\n\nhttp {\n    [...]\n}\n\n\n\n\n(Optional) Increase the maximum file upload size\n\n\nSome bookmark dumps generated by web browsers can be \nhuge\n due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.\n\n\nTo increase upload size, you will need to modify both nginx and PHP configuration:\n\n\n# /etc/nginx/nginx.conf\n\nhttp {\n    [...]\n\n    client_max_body_size 10m;\n\n    [...]\n}\n\n\n\n\n# /etc/php5/fpm/php.ini\n\n[...]\npost_max_size = 10M\n[...]\nupload_max_filesize = 10M\n\n\n\n\nMinimal\n\n\nWARNING: Use for development only!\n \n\n\nuser john users;\nworker_processes  1;\nevents {\n    worker_connections  1024;\n}\n\nhttp {\n    include            mime.types;\n    default_type       application/octet-stream;\n    keepalive_timeout  20;\n\n    index index.html index.php;\n\n    server {\n        listen       80;\n        server_name  localhost;\n        root         /home/john/web;\n\n        access_log  /var/log/nginx/access.log;\n        error_log   /var/log/nginx/error.log;\n\n        location /shaarli/ {\n            try_files $uri /shaarli/index.php$is_args$args;\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location ~ (index)\\.php$ {\n            try_files $uri =404;\n            fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n            fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;\n            fastcgi_index  index.php;\n            include        fastcgi.conf;\n        }\n    }\n}\n\n\n\n\nModular\n\n\nThe previous setup is sufficient for development purposes, but has several major caveats:\n- every content that does not match the PHP rule will be sent to client browsers:\n    - dotfiles - in our case, \n.htaccess\n\n    - temporary files, e.g. Vim or Emacs files: \nindex.php~\n\n- asset / static resource caching is not optimized\n- if serving several PHP sites, there will be a lot of duplication: \nlocation /shaarli/\n, \nlocation /mysite/\n, etc.\n\n\nTo solve this, we will split Nginx configuration in several parts, that will be included when needed:\n\n\n# /etc/nginx/deny.conf\nlocation ~ /\\. {\n    # deny access to dotfiles\n    access_log off;\n    log_not_found off;\n    deny all;\n}\n\nlocation ~ ~$ {\n    # deny access to temp editor files, e.g. \"script.php~\"\n    access_log off;\n    log_not_found off;\n    deny all;\n}\n\n\n\n\n# /etc/nginx/php.conf\nlocation ~ (index)\\.php$ {\n    # Slim - split URL path into (script_filename, path_info)\n    try_files $uri =404;\n    fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n\n    # filter and proxy PHP requests to PHP-FPM\n    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;\n    fastcgi_index  index.php;\n    include        fastcgi.conf;\n}\n\nlocation ~ \\.php$ {\n    # deny access to all other PHP scripts\n    deny all;\n}\n\n\n\n\n# /etc/nginx/static_assets.conf\nlocation ~* \\.(?:ico|css|js|gif|jpe?g|png)$ {\n    expires    max;\n    add_header Pragma public;\n    add_header Cache-Control \"public, must-revalidate, proxy-revalidate\";\n}\n\n\n\n\n# /etc/nginx/nginx.conf\n[...]\n\nhttp {\n    [...]\n\n    root        /home/john/web;\n    access_log  /var/log/nginx/access.log;\n    error_log   /var/log/nginx/error.log;\n\n    server {\n        # virtual host for a first domain\n        listen       80;\n        server_name  my.first.domain.org;\n\n        location /shaarli/ {\n            # Slim - rewrite URLs\n            try_files $uri /shaarli/index.php$is_args$args;\n\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location = /shaarli/favicon.ico {\n            # serve the Shaarli favicon from its custom location\n            alias /var/www/shaarli/images/favicon.ico;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n\n    server {\n        # virtual host for a second domain\n        listen       80;\n        server_name  second.domain.com;\n\n        location /minigal/ {\n            access_log  /var/log/nginx/minigal.access.log;\n            error_log   /var/log/nginx/minigal.error.log;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n}\n\n\n\n\nRedirect HTTP to HTTPS\n\n\nAssuming you have generated a (self-signed) key and certificate, and they are located under \n/home/john/ssl/localhost.{key,crt}\n, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.\n\n\n# /etc/nginx/nginx.conf\n[...]\n\nhttp {\n    [...]\n\n    index index.html index.php;\n\n    root        /home/john/web;\n    access_log  /var/log/nginx/access.log;\n    error_log   /var/log/nginx/error.log;\n\n    server {\n        listen       80;\n        server_name  localhost;\n\n        return 301 https://localhost$request_uri;\n    }\n\n    server {\n        listen       443 ssl;\n        server_name  localhost;\n\n        ssl_certificate      /home/john/ssl/localhost.crt;\n        ssl_certificate_key  /home/john/ssl/localhost.key;\n\n        location /shaarli/ {\n            # Slim - rewrite URLs\n            try_files $uri /index.php$is_args$args;\n\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location = /shaarli/favicon.ico {\n            # serve the Shaarli favicon from its custom location\n            alias /var/www/shaarli/images/favicon.ico;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n}",
            "title": "Server configuration"
        },
        {
            "location": "/Server-configuration/#prerequisites",
            "text": "",
            "title": "Prerequisites"
        },
        {
            "location": "/Server-configuration/#shaarli",
            "text": "Shaarli is installed in a directory readable/writeable by the user  the correct read/write permissions have been granted to the web server  user and/or group  for HTTPS / SSL:  a key pair (public, private) and a certificate have been generated  the appropriate server SSL extension is installed and active",
            "title": "Shaarli"
        },
        {
            "location": "/Server-configuration/#https-tls-and-self-signed-certificates",
            "text": "Related guides:   How to Create Self-Signed SSL Certificates with OpenSSL    How do I create my own Certificate Authority? \n* Generate a self-signed certificate (will trigger browser warnings) with apache2:  make-ssl-cert generate-default-snakeoil --force-overwrite  will create  /etc/ssl/certs/ssl-cert-snakeoil.pem  and  /etc/ssl/private/ssl-cert-snakeoil.key",
            "title": "HTTPS, TLS and self-signed certificates"
        },
        {
            "location": "/Server-configuration/#proxies",
            "text": "If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:\n-  X-Forwarded-Proto ;\n-  X-Forwarded-Host ;\n-  X-Forwarded-For .  See also  proxy-related  issues.",
            "title": "Proxies"
        },
        {
            "location": "/Server-configuration/#apache",
            "text": "",
            "title": "Apache"
        },
        {
            "location": "/Server-configuration/#minimal",
            "text": "<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n</VirtualHost>",
            "title": "Minimal"
        },
        {
            "location": "/Server-configuration/#debug-log-all-the-things",
            "text": "This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.  See:   Apache/PHP - error log per VirtualHost  (StackOverflow)   PHP: php_value vs php_admin_value and the use of php_flag explained  <VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n\n    php_flag  log_errors on\n    php_flag  display_errors on\n    php_value error_reporting 2147483647\n    php_value error_log /var/log/apache2/shaarli-php-error.log\n</VirtualHost>",
            "title": "Debug - Log all the things!"
        },
        {
            "location": "/Server-configuration/#standard-keep-access-and-error-logs",
            "text": "<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>",
            "title": "Standard - Keep access and error logs"
        },
        {
            "location": "/Server-configuration/#paranoid-redirect-http-80-to-https-443",
            "text": "See  Server-side TLS  (Mozilla).  <VirtualHost *:443>\n    ServerName   shaarli.my-domain.org\n    DocumentRoot /absolute/path/to/shaarli/\n\n    SSLEngine             on\n    SSLCertificateFile    /absolute/path/to/the/website/certificate.pem\n    SSLCertificateKeyFile /absolute/path/to/the/website/key.key\n\n    <Directory /absolute/path/to/shaarli/>\n        AllowOverride All\n        Options Indexes FollowSymLinks MultiViews\n        Order allow,deny\n        allow from all\n    </Directory>\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>\n<VirtualHost *:80>\n    ServerName   shaarli.my-domain.org\n    Redirect 301 / https://shaarli.my-domain.org\n\n    LogLevel  warn\n    ErrorLog  /var/log/apache2/shaarli-error.log\n    CustomLog /var/log/apache2/shaarli-access.log combined\n</VirtualHost>",
            "title": "Paranoid - Redirect HTTP (:80) to HTTPS (:443)"
        },
        {
            "location": "/Server-configuration/#htaccess",
            "text": "Shaarli use  .htaccess  Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive  AllowOverride All  in your virtual host configuration for them to work.  Warning : If you use Apache 2.2 or lower, you need  mod_version  to be installed and enabled.  Apache module  mod_rewrite   must  be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root  .htaccess  file.",
            "title": ".htaccess"
        },
        {
            "location": "/Server-configuration/#lighthttpd",
            "text": "",
            "title": "LightHttpd"
        },
        {
            "location": "/Server-configuration/#nginx",
            "text": "",
            "title": "Nginx"
        },
        {
            "location": "/Server-configuration/#foreword",
            "text": "Nginx does not natively interpret PHP scripts; to this effect, we will run a  FastCGI  service, to which Nginx's FastCGI module will proxy all requests to PHP resources.  Required packages:\n-  nginx \n-  php-fpm  - PHP FastCGI Process Manager  Official documentation:\n-  Beginner's guide \n-  ngx_http_fastcgi_module \n-  Pitfalls  Community resources:\n-  Server-side TLS (Nginx)  (Mozilla)\n-  PHP configuration examples  (Karl Blessing)",
            "title": "Foreword"
        },
        {
            "location": "/Server-configuration/#common-setup",
            "text": "Once Nginx and PHP-FPM are installed, we need to ensure:\n- Nginx and PHP-FPM are running using the  same user and group \n- both these user and group have\n    -  read  permissions for Shaarli resources\n    -  execute  permissions for Shaarli directories  AND  their parent directories  On a production server:\n-  user:group  will likely be  http:http ,  www:www  or  www-data:www-data \n- files will be located under  /var/www ,  /var/http  or  /usr/share/nginx  On a development server:\n- files may be located in a user's home directory\n- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!  For all following configuration examples, this user/group pair will be used:\n-  user:group = john:users ,  which corresponds to the following service configuration:  ; /etc/php/php-fpm.conf\nuser = john\ngroup = users\n\n[...]\nlisten.owner = john\nlisten.group = users  # /etc/nginx/nginx.conf\nuser john users;\n\nhttp {\n    [...]\n}",
            "title": "Common setup"
        },
        {
            "location": "/Server-configuration/#optional-increase-the-maximum-file-upload-size",
            "text": "Some bookmark dumps generated by web browsers can be  huge  due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.  To increase upload size, you will need to modify both nginx and PHP configuration:  # /etc/nginx/nginx.conf\n\nhttp {\n    [...]\n\n    client_max_body_size 10m;\n\n    [...]\n}  # /etc/php5/fpm/php.ini\n\n[...]\npost_max_size = 10M\n[...]\nupload_max_filesize = 10M",
            "title": "(Optional) Increase the maximum file upload size"
        },
        {
            "location": "/Server-configuration/#minimal_1",
            "text": "WARNING: Use for development only!    user john users;\nworker_processes  1;\nevents {\n    worker_connections  1024;\n}\n\nhttp {\n    include            mime.types;\n    default_type       application/octet-stream;\n    keepalive_timeout  20;\n\n    index index.html index.php;\n\n    server {\n        listen       80;\n        server_name  localhost;\n        root         /home/john/web;\n\n        access_log  /var/log/nginx/access.log;\n        error_log   /var/log/nginx/error.log;\n\n        location /shaarli/ {\n            try_files $uri /shaarli/index.php$is_args$args;\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location ~ (index)\\.php$ {\n            try_files $uri =404;\n            fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n            fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;\n            fastcgi_index  index.php;\n            include        fastcgi.conf;\n        }\n    }\n}",
            "title": "Minimal"
        },
        {
            "location": "/Server-configuration/#modular",
            "text": "The previous setup is sufficient for development purposes, but has several major caveats:\n- every content that does not match the PHP rule will be sent to client browsers:\n    - dotfiles - in our case,  .htaccess \n    - temporary files, e.g. Vim or Emacs files:  index.php~ \n- asset / static resource caching is not optimized\n- if serving several PHP sites, there will be a lot of duplication:  location /shaarli/ ,  location /mysite/ , etc.  To solve this, we will split Nginx configuration in several parts, that will be included when needed:  # /etc/nginx/deny.conf\nlocation ~ /\\. {\n    # deny access to dotfiles\n    access_log off;\n    log_not_found off;\n    deny all;\n}\n\nlocation ~ ~$ {\n    # deny access to temp editor files, e.g. \"script.php~\"\n    access_log off;\n    log_not_found off;\n    deny all;\n}  # /etc/nginx/php.conf\nlocation ~ (index)\\.php$ {\n    # Slim - split URL path into (script_filename, path_info)\n    try_files $uri =404;\n    fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n\n    # filter and proxy PHP requests to PHP-FPM\n    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;\n    fastcgi_index  index.php;\n    include        fastcgi.conf;\n}\n\nlocation ~ \\.php$ {\n    # deny access to all other PHP scripts\n    deny all;\n}  # /etc/nginx/static_assets.conf\nlocation ~* \\.(?:ico|css|js|gif|jpe?g|png)$ {\n    expires    max;\n    add_header Pragma public;\n    add_header Cache-Control \"public, must-revalidate, proxy-revalidate\";\n}  # /etc/nginx/nginx.conf\n[...]\n\nhttp {\n    [...]\n\n    root        /home/john/web;\n    access_log  /var/log/nginx/access.log;\n    error_log   /var/log/nginx/error.log;\n\n    server {\n        # virtual host for a first domain\n        listen       80;\n        server_name  my.first.domain.org;\n\n        location /shaarli/ {\n            # Slim - rewrite URLs\n            try_files $uri /shaarli/index.php$is_args$args;\n\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location = /shaarli/favicon.ico {\n            # serve the Shaarli favicon from its custom location\n            alias /var/www/shaarli/images/favicon.ico;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n\n    server {\n        # virtual host for a second domain\n        listen       80;\n        server_name  second.domain.com;\n\n        location /minigal/ {\n            access_log  /var/log/nginx/minigal.access.log;\n            error_log   /var/log/nginx/minigal.error.log;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n}",
            "title": "Modular"
        },
        {
            "location": "/Server-configuration/#redirect-http-to-https",
            "text": "Assuming you have generated a (self-signed) key and certificate, and they are located under  /home/john/ssl/localhost.{key,crt} , it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.  # /etc/nginx/nginx.conf\n[...]\n\nhttp {\n    [...]\n\n    index index.html index.php;\n\n    root        /home/john/web;\n    access_log  /var/log/nginx/access.log;\n    error_log   /var/log/nginx/error.log;\n\n    server {\n        listen       80;\n        server_name  localhost;\n\n        return 301 https://localhost$request_uri;\n    }\n\n    server {\n        listen       443 ssl;\n        server_name  localhost;\n\n        ssl_certificate      /home/john/ssl/localhost.crt;\n        ssl_certificate_key  /home/john/ssl/localhost.key;\n\n        location /shaarli/ {\n            # Slim - rewrite URLs\n            try_files $uri /index.php$is_args$args;\n\n            access_log  /var/log/nginx/shaarli.access.log;\n            error_log   /var/log/nginx/shaarli.error.log;\n        }\n\n        location = /shaarli/favicon.ico {\n            # serve the Shaarli favicon from its custom location\n            alias /var/www/shaarli/images/favicon.ico;\n        }\n\n        include deny.conf;\n        include static_assets.conf;\n        include php.conf;\n    }\n}",
            "title": "Redirect HTTP to HTTPS"
        },
        {
            "location": "/Server-security/",
            "text": "php.ini\n\n\nPHP settings are defined in:\n- a main configuration file, usually found under \n/etc/php5/php.ini\n; some distributions provide different configuration environments, e.g.\n    - \n/etc/php5/php.ini\n - used when running console scripts\n    - \n/etc/php5/apache2/php.ini\n - used when a client requests PHP resources from Apache\n    - \n/etc/php5/php-fpm.conf\n - used when PHP requests are proxied to PHP-FPM\n- additional configuration files/entries, depending on the installed/enabled extensions:\n    - \n/etc/php/conf.d/xdebug.ini\n\n\nLocate .ini files\n\n\nConsole environment\n\n\n$ php --ini\nConfiguration File (php.ini) Path: /etc/php\nLoaded Configuration File:         /etc/php/php.ini\nScan for additional .ini files in: /etc/php/conf.d\nAdditional .ini files parsed:      /etc/php/conf.d/xdebug.ini\n\n\n\n\nServer environment\n\n\n\n\ncreate a \nphpinfo.php\n script located in a path supported by the web server, e.g.\n\n\nApache (with user dirs enabled): \n/home/myself/public_html/phpinfo.php\n\n\n/var/www/test/phpinfo.php\n\n\n\n\n\n\nmake sure the script is readable by the web server user/group (usually, \nwww\n, \nwww-data\n or \nhttpd\n)\n\n\naccess the script from a web browser\n\n\nlook at the \nLoaded Configuration File\n and \nScan this dir for additional .ini files\n entries\n\n\n\n\n<?php phpinfo(); ?>\n\n\n\n\nfail2ban\n\n\nfail2ban\n is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses \niptables\n profiles to block brute-force attempts:\n- \nOfficial website\n\n- \nSource code\n\n\nRead Shaarli logs to ban IPs\n\n\nExample configuration:\n- allow 3 login attempts per IP address\n- after 3 failures, permanently ban the corresponding IP adddress\n\n\n/etc/fail2ban/jail.local\n\n\n[shaarli-auth]\nenabled  = true\nport     = https,http\nfilter   = shaarli-auth\nlogpath  = /var/www/path/to/shaarli/data/log.txt\nmaxretry = 3\nbantime = -1\n\n\n\n\n/etc/fail2ban/filter.d/shaarli-auth.conf\n\n\n[INCLUDES]\nbefore = common.conf\n[Definition]\nfailregex = \\s-\\s<HOST>\\s-\\sLogin failed for user.*$\nignoreregex = \n\n\n\n\nRobots - Restricting search engines and web crawler traffic\n\n\nCreating a \nrobots.txt\n with the following contents at the root of your Shaarli installation will prevent \nhonest\n web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.\n\n\nUser-agent: *\nDisallow: /\n\n\n\n\nSee:\n- http://www.robotstxt.org/\n- http://www.robotstxt.org/robotstxt.html\n- http://www.robotstxt.org/meta.html",
            "title": "Server security"
        },
        {
            "location": "/Server-security/#phpini",
            "text": "PHP settings are defined in:\n- a main configuration file, usually found under  /etc/php5/php.ini ; some distributions provide different configuration environments, e.g.\n    -  /etc/php5/php.ini  - used when running console scripts\n    -  /etc/php5/apache2/php.ini  - used when a client requests PHP resources from Apache\n    -  /etc/php5/php-fpm.conf  - used when PHP requests are proxied to PHP-FPM\n- additional configuration files/entries, depending on the installed/enabled extensions:\n    -  /etc/php/conf.d/xdebug.ini",
            "title": "php.ini"
        },
        {
            "location": "/Server-security/#locate-ini-files",
            "text": "",
            "title": "Locate .ini files"
        },
        {
            "location": "/Server-security/#console-environment",
            "text": "$ php --ini\nConfiguration File (php.ini) Path: /etc/php\nLoaded Configuration File:         /etc/php/php.ini\nScan for additional .ini files in: /etc/php/conf.d\nAdditional .ini files parsed:      /etc/php/conf.d/xdebug.ini",
            "title": "Console environment"
        },
        {
            "location": "/Server-security/#server-environment",
            "text": "create a  phpinfo.php  script located in a path supported by the web server, e.g.  Apache (with user dirs enabled):  /home/myself/public_html/phpinfo.php  /var/www/test/phpinfo.php    make sure the script is readable by the web server user/group (usually,  www ,  www-data  or  httpd )  access the script from a web browser  look at the  Loaded Configuration File  and  Scan this dir for additional .ini files  entries   <?php phpinfo(); ?>",
            "title": "Server environment"
        },
        {
            "location": "/Server-security/#fail2ban",
            "text": "fail2ban  is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses  iptables  profiles to block brute-force attempts:\n-  Official website \n-  Source code",
            "title": "fail2ban"
        },
        {
            "location": "/Server-security/#read-shaarli-logs-to-ban-ips",
            "text": "Example configuration:\n- allow 3 login attempts per IP address\n- after 3 failures, permanently ban the corresponding IP adddress  /etc/fail2ban/jail.local  [shaarli-auth]\nenabled  = true\nport     = https,http\nfilter   = shaarli-auth\nlogpath  = /var/www/path/to/shaarli/data/log.txt\nmaxretry = 3\nbantime = -1  /etc/fail2ban/filter.d/shaarli-auth.conf  [INCLUDES]\nbefore = common.conf\n[Definition]\nfailregex = \\s-\\s<HOST>\\s-\\sLogin failed for user.*$\nignoreregex =",
            "title": "Read Shaarli logs to ban IPs"
        },
        {
            "location": "/Server-security/#robots-restricting-search-engines-and-web-crawler-traffic",
            "text": "Creating a  robots.txt  with the following contents at the root of your Shaarli installation will prevent  honest  web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.  User-agent: *\nDisallow: /  See:\n- http://www.robotstxt.org/\n- http://www.robotstxt.org/robotstxt.html\n- http://www.robotstxt.org/meta.html",
            "title": "Robots - Restricting search engines and web crawler traffic"
        },
        {
            "location": "/Shaarli-configuration/",
            "text": "Foreword\n\n\nDo not edit configuration options in index.php! Your changes would be lost.\n \n\n\nOnce your Shaarli instance is installed, the file \ndata/config.json.php\n is generated:\n\n it contains all settings in JSON format, and can be edited to customize values\n\n it defines which \nplugins\n are enabled\n\n\n its values override those defined in \nindex.php\n\n\n it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration\n\n\nFile and directory permissions\n\n\nThe server process running Shaarli must have:\n\n\n\n\nread\n access to the following resources:\n\n\nPHP scripts: \nindex.php\n, \napplication/*.php\n, \nplugins/*.php\n\n\n3rd party PHP and Javascript libraries: \ninc/*.php\n, \ninc/*.js\n\n\nstatic assets:\n\n\nCSS stylesheets: \ninc/*.css\n\n\nimages/*\n\n\n\n\n\n\nRainTPL templates: \ntpl/*.html\n\n\n\n\n\n\nread\n, \nwrite\n and \nexecution\n access to the following directories:\n\n\ncache\n - thumbnail cache\n\n\ndata\n - link data store, configuration options\n\n\npagecache\n - Atom/RSS feed cache\n\n\ntmp\n - RainTPL page cache\n\n\n\n\n\n\n\n\nOn a Linux distribution:\n\n\n\n\nthe web server user will likely be \nwww\n or \nhttp\n (for Apache2)\n\n\nit will be a member of a group of the same name: \nwww:www\n, \nhttp:http\n\n\nto give it access to Shaarli, either:\n\n\nunzip Shaarli in the default web server location (usually \n/var/www/\n) and set the web server user as the owner\n\n\nput users in the same group as the web server, and set the appropriate access rights\n\n\n\n\n\n\nif you have a domain / subdomain to serve Shaarli, \nconfigure the server\n accordingly\n\n\n\n\nConfiguration\n\n\nIn \ndata/config.json.php\n.\n\n\nSee also \nPlugin System\n.\n\n\nCredentials\n\n\n\n\nYou shouldn't edit those.\n\n\n\n\nlogin\n: Login username.\n\n\nhash\n: Generated password hash.\n\n\nsalt\n: Password salt.\n\n\nGeneral\n\n\ntitle\n: Shaarli's instance title.\n\n\nheader_link\n: Link to the homepage.\n\n\nlinks_per_page\n: Number of shaares displayed per page.\n\n\ntimezone\n: See \nthe list of supported timezones\n.\n\n\nenabled_plugins\n: List of enabled plugins.\n\n\nSecurity\n\n\nsession_protection_disabled\n: Disable session cookie hijacking protection (not recommended). \nIt might be useful if your IP adress often changes.\n\n\nban_after\n: Failed login attempts before being IP banned.\n\n\nban_duration\n: IP ban duration in seconds.\n\n\nopen_shaarli\n: Anyone can add a new link while logged out if enabled.\n\n\ntrusted_proxies\n: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.\n\n\nallowed_protocols\n: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store \njavascript:\n links (bookmarklets) in Shaarli (default: \n[\"ftp\", \"ftps\", \"magnet\"]\n).\n\n\nResources\n\n\ndata_dir\n: Data directory.\n\n\ndatastore\n: Shaarli's links database file path.\n\n\nhistory\n: Shaarli's operation history file path.\n\nupdates\n: File path for the ran updates file.\n\n\nlog\n: Log file path.\n\n\nupdate_check\n: Last update check file path.\n\n\nraintpl_tpl\n: Templates directory.\n\n\nraintpl_tmp\n: Template engine cache directory.\n\n\nthumbnails_cache\n: Thumbnails cache directory.\n\n\npage_cache\n: Shaarli's internal cache directory.\n\n\nban_file\n: Banned IP file path.\n\n\nUpdates\n\n\ncheck_updates\n: Enable or disable update check to the git repository.\n\n\ncheck_updates_branch\n: Git branch used to check updates (e.g. \nstable\n or \nmaster\n).\n\n\ncheck_updates_interval\n: Look for new version every N seconds (default: every day).\n\n\nPrivacy\n\n\ndefault_private_links\n: Check the private checkbox by default for every new link.\n\n\nhide_public_links\n: All links are hidden while logged out.\n\n\nhide_timestamps\n: Timestamps are hidden.\n\n\nFeed\n\n\nrss_permalinks\n: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.\n\n\nshow_atom\n: Display ATOM feed button.\n\n\nThumbnail\n\n\nenable_thumbnails\n: Enable or disable thumbnail display.\n\n\nenable_localcache\n: Enable or disable local cache.\n\n\nRedirector\n\n\nurl\n: Redirector URL, such as \nanonym.to\n.\n\n\nencode_url\n: Enable this if the redirector needs encoded URL to work properly.\n\n\nConfiguration file example\n\n\n<?php /*\n{\n    \"credentials\": {\n        \"login\": \"<login>\",\n        \"hash\": \"<password hash>\",\n        \"salt\": \"<password salt>\"\n    },\n    \"security\": {\n        \"ban_after\": 4,\n        \"session_protection_disabled\": false,\n        \"ban_duration\": 1800,\n        \"trusted_proxies\": [\n            \"1.2.3.4\",\n            \"5.6.7.8\"\n        ],\n        \"allowed_protocols\": [\n            \"ftp\",\n            \"ftps\",\n            \"magnet\"\n        ]\n    },\n    \"resources\": {\n        \"data_dir\": \"data\",\n        \"config\": \"data\\/config.php\",\n        \"datastore\": \"data\\/datastore.php\",\n        \"ban_file\": \"data\\/ipbans.php\",\n        \"updates\": \"data\\/updates.txt\",\n        \"log\": \"data\\/log.txt\",\n        \"update_check\": \"data\\/lastupdatecheck.txt\",\n        \"raintpl_tmp\": \"tmp\\/\",\n        \"raintpl_tpl\": \"tpl\\/\",\n        \"thumbnails_cache\": \"cache\",\n        \"page_cache\": \"pagecache\"\n    },\n    \"general\": {\n        \"check_updates\": true,\n        \"rss_permalinks\": true,\n        \"links_per_page\": 20,\n        \"default_private_links\": true,\n        \"enable_thumbnails\": true,\n        \"enable_localcache\": true,\n        \"check_updates_branch\": \"stable\",\n        \"check_updates_interval\": 86400,\n        \"enabled_plugins\": [\n            \"markdown\",\n            \"wallabag\",\n            \"archiveorg\"\n        ],\n        \"timezone\": \"Europe\\/Paris\",\n        \"title\": \"My Shaarli\",\n        \"header_link\": \"?\"\n    },\n    \"extras\": {\n        \"show_atom\": false,\n        \"hide_public_links\": false,\n        \"hide_timestamps\": false,\n        \"open_shaarli\": false,\n        \"redirector\": \"http://anonym.to/?\",\n        \"redirector_encode_url\": false\n    },\n    \"general\": {\n        \"header_link\": \"?\",\n        \"links_per_page\": 20,\n        \"enabled_plugins\": [\n            \"markdown\",\n            \"wallabag\"\n        ],\n        \"timezone\": \"Europe\\/Paris\",\n        \"title\": \"My Shaarli\"\n    },\n    \"updates\": {\n        \"check_updates\": true,\n        \"check_updates_branch\": \"stable\",\n        \"check_updates_interval\": 86400\n    },\n    \"feed\": {\n        \"rss_permalinks\": true,\n        \"show_atom\": false\n    },\n    \"privacy\": {\n        \"default_private_links\": true,\n        \"hide_public_links\": false,\n        \"hide_timestamps\": false\n    },\n    \"thumbnail\": {\n        \"enable_thumbnails\": true,\n        \"enable_localcache\": true\n    },\n    \"redirector\": {\n        \"url\": \"http://anonym.to/?\",\n        \"encode_url\": false\n    },\n    \"plugins\": {\n        \"WALLABAG_URL\": \"http://demo.wallabag.org\",\n        \"WALLABAG_VERSION\": \"1\"\n    }\n} ?>\n\n\n\n\nAdditional configuration\n\n\nThe playvideos plugin may require that you adapt your server's \n\nContent Security Policy\n \nconfiguration to work properly.",
            "title": "Shaarli configuration"
        },
        {
            "location": "/Shaarli-configuration/#foreword",
            "text": "Do not edit configuration options in index.php! Your changes would be lost.    Once your Shaarli instance is installed, the file  data/config.json.php  is generated:  it contains all settings in JSON format, and can be edited to customize values  it defines which  plugins  are enabled   its values override those defined in  index.php   it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration",
            "title": "Foreword"
        },
        {
            "location": "/Shaarli-configuration/#file-and-directory-permissions",
            "text": "The server process running Shaarli must have:   read  access to the following resources:  PHP scripts:  index.php ,  application/*.php ,  plugins/*.php  3rd party PHP and Javascript libraries:  inc/*.php ,  inc/*.js  static assets:  CSS stylesheets:  inc/*.css  images/*    RainTPL templates:  tpl/*.html    read ,  write  and  execution  access to the following directories:  cache  - thumbnail cache  data  - link data store, configuration options  pagecache  - Atom/RSS feed cache  tmp  - RainTPL page cache     On a Linux distribution:   the web server user will likely be  www  or  http  (for Apache2)  it will be a member of a group of the same name:  www:www ,  http:http  to give it access to Shaarli, either:  unzip Shaarli in the default web server location (usually  /var/www/ ) and set the web server user as the owner  put users in the same group as the web server, and set the appropriate access rights    if you have a domain / subdomain to serve Shaarli,  configure the server  accordingly",
            "title": "File and directory permissions"
        },
        {
            "location": "/Shaarli-configuration/#configuration",
            "text": "In  data/config.json.php .  See also  Plugin System .",
            "title": "Configuration"
        },
        {
            "location": "/Shaarli-configuration/#credentials",
            "text": "You shouldn't edit those.   login : Login username.  hash : Generated password hash.  salt : Password salt.",
            "title": "Credentials"
        },
        {
            "location": "/Shaarli-configuration/#general",
            "text": "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 .  enabled_plugins : List of enabled plugins.",
            "title": "General"
        },
        {
            "location": "/Shaarli-configuration/#security",
            "text": "session_protection_disabled : Disable session cookie hijacking protection (not recommended). \nIt might be useful if your IP adress often changes.  ban_after : Failed login attempts before being IP banned.  ban_duration : IP ban duration in seconds.  open_shaarli : Anyone can add a new link while logged out if enabled.  trusted_proxies : List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.  allowed_protocols : List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store  javascript:  links (bookmarklets) in Shaarli (default:  [\"ftp\", \"ftps\", \"magnet\"] ).",
            "title": "Security"
        },
        {
            "location": "/Shaarli-configuration/#resources",
            "text": "data_dir : Data directory.  datastore : Shaarli's links database file path.  history : Shaarli's operation history file path. updates : File path for the ran updates file.  log : Log file path.  update_check : Last update check file path.  raintpl_tpl : Templates directory.  raintpl_tmp : Template engine cache directory.  thumbnails_cache : Thumbnails cache directory.  page_cache : Shaarli's internal cache directory.  ban_file : Banned IP file path.",
            "title": "Resources"
        },
        {
            "location": "/Shaarli-configuration/#updates",
            "text": "check_updates : Enable or disable update check to the git repository.  check_updates_branch : Git branch used to check updates (e.g.  stable  or  master ).  check_updates_interval : Look for new version every N seconds (default: every day).",
            "title": "Updates"
        },
        {
            "location": "/Shaarli-configuration/#privacy",
            "text": "default_private_links : Check the private checkbox by default for every new link.  hide_public_links : All links are hidden while logged out.  hide_timestamps : Timestamps are hidden.",
            "title": "Privacy"
        },
        {
            "location": "/Shaarli-configuration/#feed",
            "text": "rss_permalinks : Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.  show_atom : Display ATOM feed button.",
            "title": "Feed"
        },
        {
            "location": "/Shaarli-configuration/#thumbnail",
            "text": "enable_thumbnails : Enable or disable thumbnail display.  enable_localcache : Enable or disable local cache.",
            "title": "Thumbnail"
        },
        {
            "location": "/Shaarli-configuration/#redirector",
            "text": "url : Redirector URL, such as  anonym.to .  encode_url : Enable this if the redirector needs encoded URL to work properly.",
            "title": "Redirector"
        },
        {
            "location": "/Shaarli-configuration/#configuration-file-example",
            "text": "<?php /*\n{\n    \"credentials\": {\n        \"login\": \"<login>\",\n        \"hash\": \"<password hash>\",\n        \"salt\": \"<password salt>\"\n    },\n    \"security\": {\n        \"ban_after\": 4,\n        \"session_protection_disabled\": false,\n        \"ban_duration\": 1800,\n        \"trusted_proxies\": [\n            \"1.2.3.4\",\n            \"5.6.7.8\"\n        ],\n        \"allowed_protocols\": [\n            \"ftp\",\n            \"ftps\",\n            \"magnet\"\n        ]\n    },\n    \"resources\": {\n        \"data_dir\": \"data\",\n        \"config\": \"data\\/config.php\",\n        \"datastore\": \"data\\/datastore.php\",\n        \"ban_file\": \"data\\/ipbans.php\",\n        \"updates\": \"data\\/updates.txt\",\n        \"log\": \"data\\/log.txt\",\n        \"update_check\": \"data\\/lastupdatecheck.txt\",\n        \"raintpl_tmp\": \"tmp\\/\",\n        \"raintpl_tpl\": \"tpl\\/\",\n        \"thumbnails_cache\": \"cache\",\n        \"page_cache\": \"pagecache\"\n    },\n    \"general\": {\n        \"check_updates\": true,\n        \"rss_permalinks\": true,\n        \"links_per_page\": 20,\n        \"default_private_links\": true,\n        \"enable_thumbnails\": true,\n        \"enable_localcache\": true,\n        \"check_updates_branch\": \"stable\",\n        \"check_updates_interval\": 86400,\n        \"enabled_plugins\": [\n            \"markdown\",\n            \"wallabag\",\n            \"archiveorg\"\n        ],\n        \"timezone\": \"Europe\\/Paris\",\n        \"title\": \"My Shaarli\",\n        \"header_link\": \"?\"\n    },\n    \"extras\": {\n        \"show_atom\": false,\n        \"hide_public_links\": false,\n        \"hide_timestamps\": false,\n        \"open_shaarli\": false,\n        \"redirector\": \"http://anonym.to/?\",\n        \"redirector_encode_url\": false\n    },\n    \"general\": {\n        \"header_link\": \"?\",\n        \"links_per_page\": 20,\n        \"enabled_plugins\": [\n            \"markdown\",\n            \"wallabag\"\n        ],\n        \"timezone\": \"Europe\\/Paris\",\n        \"title\": \"My Shaarli\"\n    },\n    \"updates\": {\n        \"check_updates\": true,\n        \"check_updates_branch\": \"stable\",\n        \"check_updates_interval\": 86400\n    },\n    \"feed\": {\n        \"rss_permalinks\": true,\n        \"show_atom\": false\n    },\n    \"privacy\": {\n        \"default_private_links\": true,\n        \"hide_public_links\": false,\n        \"hide_timestamps\": false\n    },\n    \"thumbnail\": {\n        \"enable_thumbnails\": true,\n        \"enable_localcache\": true\n    },\n    \"redirector\": {\n        \"url\": \"http://anonym.to/?\",\n        \"encode_url\": false\n    },\n    \"plugins\": {\n        \"WALLABAG_URL\": \"http://demo.wallabag.org\",\n        \"WALLABAG_VERSION\": \"1\"\n    }\n} ?>",
            "title": "Configuration file example"
        },
        {
            "location": "/Shaarli-configuration/#additional-configuration",
            "text": "The playvideos plugin may require that you adapt your server's  Content Security Policy  \nconfiguration to work properly.",
            "title": "Additional configuration"
        },
        {
            "location": "/Plugins/",
            "text": "Plugin installation\n\n\nThere is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.\n\n\nIf you want to install a third party plugin:\n\n\n\n\nDownload it.\n\n\nPut it in the \nplugins\n directory in Shaarli's installation folder.\n\n\nMake sure you put it correctly:\n\n\n\n\n| index.php\n| plugins/\n|---| custom_plugin/\n|   |---| custom_plugin.php\n|   |---| ...\n\n\n\n\n\n\n\nMake sure your webserver can read and write the files in your plugin folder.\n\n\n\n\nPlugin configuration\n\n\nIn Shaarli's administration page (\nTools\n link), go to \nPlugin administration\n.\n\n\nHere you can enable and disable all plugins available, and configure them.\n\n\n\n\nPlugin order\n\n\nIn 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.\n\n\nThis is important in case plugins are depending on each other. Read plugins README details for more information.\n\n\nUse case\n: The (non existent) plugin \nshaares_footer\n adds a footer to every shaare in Markdown syntax. It needs to be processed \nbefore\n (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.\n\n\nFile mode\n\n\nEnabled plugin are stored in your \nconfig.php\n parameters file, under the \narray\n:\n\n\n$GLOBALS['config']['ENABLED_PLUGINS']\n\n\n\n\nYou can edit them manually here.\nExample:\n\n\n$GLOBALS['config']['ENABLED_PLUGINS'] = array(\n    'qrcode', \n    'archiveorg',\n    'wallabag',\n    'markdown',\n);\n\n\n\n\nPlugin usage\n\n\nOfficial plugins\n\n\nUsage of each plugin is documented in it's README file:\n\n\n\n\naddlink-toolbar\n: Adds the addlink input on the linklist page\n\n\narchiveorg\n: For each link, add an Archive.org icon\n\n\nmarkdown\n: Render shaare description with Markdown syntax.\n\n\nplayvideos\n: Add a button in the toolbar allowing to watch all videos.\n\n\nqrcode\n: For each link, add a QRCode icon.\n\n\nwallabag\n:  For each link, add a Wallabag icon to save it in your instance.\n\n\n\n\nThird party plugins\n\n\nSee \nCommunity & related software",
            "title": "Plugins"
        },
        {
            "location": "/Plugins/#plugin-installation",
            "text": "There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.  If you want to install a third party plugin:   Download it.  Put it in the  plugins  directory in Shaarli's installation folder.  Make sure you put it correctly:   | index.php\n| plugins/\n|---| custom_plugin/\n|   |---| custom_plugin.php\n|   |---| ...   Make sure your webserver can read and write the files in your plugin folder.",
            "title": "Plugin installation"
        },
        {
            "location": "/Plugins/#plugin-configuration",
            "text": "In Shaarli's administration page ( Tools  link), go to  Plugin administration .  Here you can enable and disable all plugins available, and configure them.",
            "title": "Plugin configuration"
        },
        {
            "location": "/Plugins/#plugin-order",
            "text": "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 are depending on each other. Read plugins README details 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.",
            "title": "Plugin order"
        },
        {
            "location": "/Plugins/#file-mode",
            "text": "Enabled plugin are stored in your  config.php  parameters file, under the  array :  $GLOBALS['config']['ENABLED_PLUGINS']  You can edit them manually here.\nExample:  $GLOBALS['config']['ENABLED_PLUGINS'] = array(\n    'qrcode', \n    'archiveorg',\n    'wallabag',\n    'markdown',\n);",
            "title": "File mode"
        },
        {
            "location": "/Plugins/#plugin-usage",
            "text": "",
            "title": "Plugin usage"
        },
        {
            "location": "/Plugins/#official-plugins",
            "text": "Usage of each plugin is documented in it's README file:   addlink-toolbar : Adds the addlink input on the linklist page  archiveorg : For each link, add an Archive.org icon  markdown : Render shaare description with Markdown syntax.  playvideos : Add a button in the toolbar allowing to watch all videos.  qrcode : For each link, add a QRCode icon.  wallabag :  For each link, add a Wallabag icon to save it in your instance.",
            "title": "Official plugins"
        },
        {
            "location": "/Plugins/#third-party-plugins",
            "text": "See  Community & related software",
            "title": "Third party plugins"
        },
        {
            "location": "/docker/docker-101/",
            "text": "Basics\n\n\nInstall \nDocker\n, by following the instructions relevant\nto your OS / distribution, and start the service.\n\n\nSearch an image on \nDockerHub\n\n\n$ docker search debian\n\nNAME            DESCRIPTION                                     STARS   OFFICIAL   AUTOMATED\nubuntu          Ubuntu is a Debian-based Linux operating s...   2065    [OK]\ndebian          Debian is a Linux distribution that's comp...   603     [OK]\ngoogle/debian                                                   47                 [OK]\n\n\n\n\nShow available tags for a repository\n\n\n$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool\n\n% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\nDload  Upload   Total   Spent    Left  Speed\n100  1283    0  1283    0     0    433      0 --:--:--  0:00:02 --:--:--   433\n\n\n\n\nSample output:\n\n\n[\n    {\n        \"layer\": \"85a02782\",\n        \"name\": \"stretch\"\n    },\n    {\n        \"layer\": \"59abecbc\",\n        \"name\": \"testing\"\n    },\n    {\n        \"layer\": \"bf0fd686\",\n        \"name\": \"unstable\"\n    },\n    {\n        \"layer\": \"60c52dbe\",\n        \"name\": \"wheezy\"\n    },\n    {\n        \"layer\": \"c5b806fe\",\n        \"name\": \"wheezy-backports\"\n    }\n]\n\n\n\n\n\nPull an image from DockerHub\n\n\n$ docker pull repository[:tag]\n\n$ docker pull debian:wheezy\nwheezy: Pulling from debian\n4c8cbfd2973e: Pull complete\n60c52dbe9d91: Pull complete\nDigest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe\nStatus: Downloaded newer image for debian:wheezy",
            "title": "Docker 101"
        },
        {
            "location": "/docker/docker-101/#basics",
            "text": "Install  Docker , by following the instructions relevant\nto your OS / distribution, and start the service.",
            "title": "Basics"
        },
        {
            "location": "/docker/docker-101/#search-an-image-on-dockerhub",
            "text": "$ docker search debian\n\nNAME            DESCRIPTION                                     STARS   OFFICIAL   AUTOMATED\nubuntu          Ubuntu is a Debian-based Linux operating s...   2065    [OK]\ndebian          Debian is a Linux distribution that's comp...   603     [OK]\ngoogle/debian                                                   47                 [OK]",
            "title": "Search an image on DockerHub"
        },
        {
            "location": "/docker/docker-101/#show-available-tags-for-a-repository",
            "text": "$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool\n\n% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\nDload  Upload   Total   Spent    Left  Speed\n100  1283    0  1283    0     0    433      0 --:--:--  0:00:02 --:--:--   433  Sample output:  [\n    {\n        \"layer\": \"85a02782\",\n        \"name\": \"stretch\"\n    },\n    {\n        \"layer\": \"59abecbc\",\n        \"name\": \"testing\"\n    },\n    {\n        \"layer\": \"bf0fd686\",\n        \"name\": \"unstable\"\n    },\n    {\n        \"layer\": \"60c52dbe\",\n        \"name\": \"wheezy\"\n    },\n    {\n        \"layer\": \"c5b806fe\",\n        \"name\": \"wheezy-backports\"\n    }\n]",
            "title": "Show available tags for a repository"
        },
        {
            "location": "/docker/docker-101/#pull-an-image-from-dockerhub",
            "text": "$ docker pull repository[:tag]\n\n$ docker pull debian:wheezy\nwheezy: Pulling from debian\n4c8cbfd2973e: Pull complete\n60c52dbe9d91: Pull complete\nDigest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe\nStatus: Downloaded newer image for debian:wheezy",
            "title": "Pull an image from DockerHub"
        },
        {
            "location": "/docker/shaarli-images/",
            "text": "Get and run a Shaarli image\n\n\nDockerHub repository\n\n\nThe images can be found in the \nshaarli/shaarli\n\nrepository.\n\n\nAvailable image tags\n\n\n\n\nlatest\n: master branch (tarball release)\n\n\nstable\n: stable branch (tarball release)\n\n\n\n\nAll images rely on:\n- \nDebian 8 Jessie\n\n- \nPHP5-FPM\n\n- \nNginx\n\n\nDownload from DockerHub\n\n\n$ docker pull shaarli/shaarli\nlatest: Pulling from shaarli/shaarli\n32716d9fcddb: Pull complete\n84899d045435: Pull complete\n4b6ad7444763: Pull complete\ne0345ef7a3e0: Pull complete\n5c1dd344094f: Pull complete\n6422305a200b: Pull complete\n7d63f861dbef: Pull complete\n3eb97210645c: Pull complete\n869319d746ff: Already exists\n869319d746ff: Pulling fs layer\n902b87aaaec9: Already exists\nDigest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98\nStatus: Downloaded newer image for shaarli/shaarli:latest\n\n\n\n\nCreate and start a new container from the image\n\n\n# map the host's :8000 port to the container's :80 port\n$ docker create -p 8000:80 shaarli/shaarli\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# launch the container in the background\n$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# list active containers\n$ docker ps\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES\nd40b7af693d6  shaarli/shaarli  /usr/bin/supervisor  15 seconds ago  Up 4 seconds  0.0.0.0:8000->80/tcp  backstabbing_galileo\n\n\n\n\nStop and destroy a container\n\n\n$ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!\nbackstabbing_galileo\n\n# check the container is stopped\n$ docker ps\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES\n\n# list ALL containers\n$ docker ps -a\nCONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                      PORTS               NAMES\nd40b7af693d6        shaarli/shaarli     /usr/bin/supervisor   5 minutes ago       Exited (0) 48 seconds ago                       backstabbing_galileo\n\n# destroy the container\n$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices\nbackstabbing_galileo\n\n$ docker ps -a\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES",
            "title": "Shaarli images"
        },
        {
            "location": "/docker/shaarli-images/#get-and-run-a-shaarli-image",
            "text": "",
            "title": "Get and run a Shaarli image"
        },
        {
            "location": "/docker/shaarli-images/#dockerhub-repository",
            "text": "The images can be found in the  shaarli/shaarli \nrepository.",
            "title": "DockerHub repository"
        },
        {
            "location": "/docker/shaarli-images/#available-image-tags",
            "text": "latest : master branch (tarball release)  stable : stable branch (tarball release)   All images rely on:\n-  Debian 8 Jessie \n-  PHP5-FPM \n-  Nginx",
            "title": "Available image tags"
        },
        {
            "location": "/docker/shaarli-images/#download-from-dockerhub",
            "text": "$ docker pull shaarli/shaarli\nlatest: Pulling from shaarli/shaarli\n32716d9fcddb: Pull complete\n84899d045435: Pull complete\n4b6ad7444763: Pull complete\ne0345ef7a3e0: Pull complete\n5c1dd344094f: Pull complete\n6422305a200b: Pull complete\n7d63f861dbef: Pull complete\n3eb97210645c: Pull complete\n869319d746ff: Already exists\n869319d746ff: Pulling fs layer\n902b87aaaec9: Already exists\nDigest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98\nStatus: Downloaded newer image for shaarli/shaarli:latest",
            "title": "Download from DockerHub"
        },
        {
            "location": "/docker/shaarli-images/#create-and-start-a-new-container-from-the-image",
            "text": "# map the host's :8000 port to the container's :80 port\n$ docker create -p 8000:80 shaarli/shaarli\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# launch the container in the background\n$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# list active containers\n$ docker ps\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES\nd40b7af693d6  shaarli/shaarli  /usr/bin/supervisor  15 seconds ago  Up 4 seconds  0.0.0.0:8000->80/tcp  backstabbing_galileo",
            "title": "Create and start a new container from the image"
        },
        {
            "location": "/docker/shaarli-images/#stop-and-destroy-a-container",
            "text": "$ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!\nbackstabbing_galileo\n\n# check the container is stopped\n$ docker ps\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES\n\n# list ALL containers\n$ docker ps -a\nCONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                      PORTS               NAMES\nd40b7af693d6        shaarli/shaarli     /usr/bin/supervisor   5 minutes ago       Exited (0) 48 seconds ago                       backstabbing_galileo\n\n# destroy the container\n$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices\nbackstabbing_galileo\n\n$ docker ps -a\nCONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES",
            "title": "Stop and destroy a container"
        },
        {
            "location": "/docker/reverse-proxy-configuration/",
            "text": "TODO, see https://github.com/shaarli/Shaarli/issues/888\n\n\nHAProxy\n\n\nNginx",
            "title": "Reverse proxy configuration"
        },
        {
            "location": "/docker/reverse-proxy-configuration/#haproxy",
            "text": "",
            "title": "HAProxy"
        },
        {
            "location": "/docker/reverse-proxy-configuration/#nginx",
            "text": "",
            "title": "Nginx"
        },
        {
            "location": "/docker/resources/",
            "text": "Docker\n\n\n\n\nInteractive Docker training portal\n on \nKatakoda\n\n\nWhere are Docker images stored?\n\n\nDockerfile reference\n\n\nDockerfile best practices\n\n\nVolumes\n\n\n\n\nDockerHub\n\n\n\n\nRepositories\n\n\nTeams and organizations\n\n\nGitHub automated build\n\n\n\n\nService management\n\n\n\n\nUsing supervisord\n\n\nNginx in the foreground\n\n\nsupervisord",
            "title": "Docker resources"
        },
        {
            "location": "/docker/resources/#docker",
            "text": "Interactive Docker training portal  on  Katakoda  Where are Docker images stored?  Dockerfile reference  Dockerfile best practices  Volumes",
            "title": "Docker"
        },
        {
            "location": "/docker/resources/#dockerhub",
            "text": "Repositories  Teams and organizations  GitHub automated build",
            "title": "DockerHub"
        },
        {
            "location": "/docker/resources/#service-management",
            "text": "Using supervisord  Nginx in the foreground  supervisord",
            "title": "Service management"
        },
        {
            "location": "/Features/",
            "text": "Main features\n\n\nShaarli is intended:\n * to share, comment and save interesting links and news\n * to bookmark useful/frequent personal links (as private links) and share them between computers\n * as a minimal blog/microblog/writing platform (no character limit)\n * as a read-it-later list (for example items tagged \nreadlater\n)\n * to draft and save articles/ideas\n * to keep code snippets\n * to keep notes and documentation\n * as a shared clipboard between machines\n * as a todo list\n * to store playlists (e.g. with the \nmusic\n or \nvideo\n tags)\n * to keep extracts/comments from webpages that may disappear\n * to keep track of ongoing discussions (for example items tagged \ndiscussion\n)\n * \nto feed RSS aggregators\n (planets) with specific tags\n * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)\n\n\nUsing Shaarli as a blog, notepad, pastebin...\n\n\n\n\nGo to your Shaarli setup and log in\n\n\nClick the \nAdd Link\n button\n\n\nTo share text only, do not enter any URL in the corresponding input field and click \nAdd Link\n\n\nPick a title and enter your article, or note, in the description field; add a few tags; optionally check \nPrivate\n then click \nSave\n\n\nVoil\u00e0!  Your article is now published (privately if you selected that option) and accessible using its permalink.",
            "title": "Features"
        },
        {
            "location": "/Features/#main-features",
            "text": "Shaarli is intended:\n * to share, comment and save interesting links and news\n * to bookmark useful/frequent personal links (as private links) and share them between computers\n * as a minimal blog/microblog/writing platform (no character limit)\n * as a read-it-later list (for example items tagged  readlater )\n * to draft and save articles/ideas\n * to keep code snippets\n * to keep notes and documentation\n * as a shared clipboard between machines\n * as a todo list\n * to store playlists (e.g. with the  music  or  video  tags)\n * to keep extracts/comments from webpages that may disappear\n * to keep track of ongoing discussions (for example items tagged  discussion )\n *  to feed RSS aggregators  (planets) with specific tags\n * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)",
            "title": "Main features"
        },
        {
            "location": "/Features/#using-shaarli-as-a-blog-notepad-pastebin",
            "text": "Go to your Shaarli setup and log in  Click the  Add Link  button  To share text only, do not enter any URL in the corresponding input field and click  Add Link  Pick a title and enter your article, or note, in the description field; add a few tags; optionally check  Private  then click  Save  Voil\u00e0!  Your article is now published (privately if you selected that option) and accessible using its permalink.",
            "title": "Using Shaarli as a blog, notepad, pastebin..."
        },
        {
            "location": "/Bookmarklet/",
            "text": "Add the sharing button (\nbookmarklet\n) to your browser\n\n\n\n\nOpen your Shaarli and \nLogin\n\n\nClick the \nTools\n button in the top bar\n\n\nDrag the \n\u271aShaare link\n button\n, and drop it to your browser's bookmarks bar.\n\n\n\n\nThis bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. 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.\n\n\n\n\nShare links using the \nbookmarklet\n\n\n\n\nWhen you are visiting a webpage you would like to share with Shaarli, click the \nbookmarklet\n you just added.\n\n\nA window opens.\n\n\nYou can freely edit title, description, tags... to find it later using the text search or tag filtering.\n\n\nYou will be able to edit this link later using the \n edit button.\n\n\nYou can also check the \u201cPrivate\u201d box so that the link is saved but only visible to you. \n\n\nClick \nSave\n.\nVoil\u00e0! Your link is now shared.\n\n\n\n\nTroubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)\n\n\nWebsites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.\n\n\nSee \n#196\n.\n\n\nThere is an open bug for both Firefox and Chromium:\n\n\n\n\nhttps://bugzilla.mozilla.org/show_bug.cgi?id=866522\n\n\nhttps://code.google.com/p/chromium/issues/detail?id=233903",
            "title": "Bookmarklet"
        },
        {
            "location": "/Bookmarklet/#add-the-sharing-button-bookmarklet-to-your-browser",
            "text": "Open your Shaarli and  Login  Click the  Tools  button in the top bar  Drag the  \u271aShaare link  button , and drop it to your browser's bookmarks bar.   This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. 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.",
            "title": "Add the sharing button (bookmarklet) to your browser"
        },
        {
            "location": "/Bookmarklet/#share-links-using-the-bookmarklet",
            "text": "When you are visiting a webpage you would like to share with Shaarli, click the  bookmarklet  you just added.  A window opens.  You can freely edit title, description, tags... to find it later using the text search or tag filtering.  You will be able to edit this link later using the   edit button.  You can also check the \u201cPrivate\u201d box so that the link is saved but only visible to you.   Click  Save . Voil\u00e0! Your link is now shared.",
            "title": "Share links using the bookmarklet"
        },
        {
            "location": "/Bookmarklet/#troubleshooting-the-bookmarklet-doesnt-work-with-a-few-website-eg-githubcom",
            "text": "Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.  See  #196 .  There is an open bug for both Firefox and Chromium:   https://bugzilla.mozilla.org/show_bug.cgi?id=866522  https://code.google.com/p/chromium/issues/detail?id=233903",
            "title": "Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)"
        },
        {
            "location": "/Browsing-and-searching/",
            "text": "Plain text search\n\n\nUse the \nSearch text\n field to search in \nany\n of the fields of all links (Title, URL, Description...)\n\n\nExclude text/tags:\n Use the \n-\n operator before a word or tag (example \n-uninteresting\n) to prevent entries containing (or tagged) \nuninteresting\n from showing up in the search results.\n\n\nExact text search:\n Use double-quotes (example \n\"exact search\"\n) to search for the exact expression.\n\n\nBoth exclude patterns and exact searches can be combined with normal searches (example \n\"exact search\" term otherterm -notthis \"very exact\" stuff -notagain\n)\n\n\nTags search\n\n\nUse the \nFilter by tags\n field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).  \n\n\nHidden tags:\n Tags starting with a dot \n.\n (example \n.secret\n) are private. They can only be seen and searched when logged in.\n\n\nAlternatively you can use the \nTag cloud\n to discover all tags and click on any of them to display related links.\n\n\nTo search for links that are not tagged, enter \n\"\"\n in the tag search field.\n\n\nFiltering RSS feeds/Picture wall\n\n\nRSS feeds can also be restricted to only return items matching a text/tag search: see \nRSS feeds\n.",
            "title": "Browsing and searching"
        },
        {
            "location": "/Browsing-and-searching/#plain-text-search",
            "text": "Use the  Search text  field to search in  any  of the fields of all links (Title, URL, Description...)  Exclude text/tags:  Use the  -  operator before a word or tag (example  -uninteresting ) to prevent entries containing (or tagged)  uninteresting  from showing up in the search results.  Exact text search:  Use double-quotes (example  \"exact search\" ) to search for the exact expression.  Both exclude patterns and exact searches can be combined with normal searches (example  \"exact search\" term otherterm -notthis \"very exact\" stuff -notagain )",
            "title": "Plain text search"
        },
        {
            "location": "/Browsing-and-searching/#tags-search",
            "text": "Use the  Filter by tags  field to restrict displayed links to entries 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.  Alternatively you can use the  Tag cloud  to discover all tags and click on any of them to display related links.  To search for links that are not tagged, enter  \"\"  in the tag search field.",
            "title": "Tags search"
        },
        {
            "location": "/Browsing-and-searching/#filtering-rss-feedspicture-wall",
            "text": "RSS feeds can also be restricted to only return items matching a text/tag search: see  RSS feeds .",
            "title": "Filtering RSS feeds/Picture wall"
        },
        {
            "location": "/Firefox-share/",
            "text": "Add Shaarli as a sharing service to Firefox\n\n\n\n\nOpen your Shaarli and \nLogin\n\n\nClick the \nTools\n button in the top bar\n\n\nClick the \n\u271aAdd to Firefox social\n button and accept the activation.\n\n\n\n\nSharing links using Firefox share\n\n\n\n\nAdd the sharing service as described above\n\n\nWhen you are visiting a webpage you would like to share with Shaarli, click the Firefox \nShare\n button \nimages/firefoxshare.png\n\n\nYou can edit your link before and after saving, just like the bookmarklet above.\n\n\n\n\n\n\n\n\n\n\n\uf06a\n\n\nYour 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 plain HTTP connections.",
            "title": "Firefox share"
        },
        {
            "location": "/Firefox-share/#add-shaarli-as-a-sharing-service-to-firefox",
            "text": "Open your Shaarli and  Login  Click the  Tools  button in the top bar  Click the  \u271aAdd to Firefox social  button and accept the activation.",
            "title": "Add Shaarli as a sharing service to Firefox"
        },
        {
            "location": "/Firefox-share/#sharing-links-using-firefox-share",
            "text": "Add the sharing service as described above  When you are visiting a webpage you would like to share with Shaarli, click the Firefox  Share  button  images/firefoxshare.png  You can edit your link before and after saving, just like the bookmarklet above.      \uf06a  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 plain HTTP connections.",
            "title": "Sharing links using Firefox share"
        },
        {
            "location": "/RSS-feeds/",
            "text": "Feeds options\n\n\nFeeds are available in ATOM with \n?do=atom\n and RSS with \ndo=RSS\n.\n\n\nOptions:\n- You can use \npermalinks\n in the feed URL to get permalink to Shaares instead of direct link to shaared URL.\n    - E.G. \nhttps://my.shaarli.domain/?do=atom&permalinks\n.\n- You can use \nnb\n parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: \n50\n). The keyword \nall\n is available if you want everything.\n    - \nhttps://my.shaarli.domain/?do=atom&permalinks&nb=42\n\n    - \nhttps://my.shaarli.domain/?do=atom&permalinks&nb=all\n\n\nRSS Feeds or Picture Wall for a specific search/tag\n\n\nIt is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to \nonly display results of a specific search, or for a specific tag\n.\n\n\nFor example, if you want to subscribe only to links tagged \nphotography\n:\n- Go to the desired Shaarli instance.\n- Search for the \nphotography\n tag in the \nFilter by tag\n box. Links tagged \nphotography\n are displayed.\n- Click on the \nRSS Feed\n button.\n- You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.\n- The same method \nalso works for a full-text search\n (\nSearch\n box) \nand for the Picture Wall\n (want to only see pictures about \nnature\n?)\n- You can also build the URLs manually: \n    - \nhttps://my.shaarli.domain/?do=rss&searchtags=nature\n\n    - \nhttps://my.shaarli.domain/links/?do=picwall&searchterm=poney",
            "title": "RSS feeds"
        },
        {
            "location": "/RSS-feeds/#feeds-options",
            "text": "Feeds are available in ATOM with  ?do=atom  and RSS with  do=RSS .  Options:\n- You can use  permalinks  in the feed URL to get permalink to Shaares instead of direct link to shaared URL.\n    - E.G.  https://my.shaarli.domain/?do=atom&permalinks .\n- You can use  nb  parameter in the feed URL 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.\n    -  https://my.shaarli.domain/?do=atom&permalinks&nb=42 \n    -  https://my.shaarli.domain/?do=atom&permalinks&nb=all",
            "title": "Feeds options"
        },
        {
            "location": "/RSS-feeds/#rss-feeds-or-picture-wall-for-a-specific-searchtag",
            "text": "It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to  only display results of a specific search, or for a specific tag .  For example, if you want to subscribe only to links tagged  photography :\n- Go to the desired Shaarli instance.\n- Search for the  photography  tag in the  Filter by tag  box. Links tagged  photography  are displayed.\n- Click on the  RSS Feed  button.\n- You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.\n- The same method  also works for a full-text search  ( Search  box)  and for the Picture Wall  (want to only see pictures about  nature ?)\n- You can also build the URLs manually: \n    -  https://my.shaarli.domain/?do=rss&searchtags=nature \n    -  https://my.shaarli.domain/links/?do=picwall&searchterm=poney",
            "title": "RSS Feeds or Picture Wall for a specific search/tag"
        },
        {
            "location": "/REST-API/",
            "text": "Usage\n\n\nSee the \nREST API documentation\n.\n\n\nAuthentication\n\n\nAll requests to Shaarli's API must include a JWT token to verify their authenticity.\n\n\nThis token has to be included as an HTTP header called \nAuthentication: Bearer <jwt token>\n.\n\n\nJWT resources :\n\n\n\n\njwt.io\n (including a list of client per language).\n\n\nRFC : https://tools.ietf.org/html/rfc7519\n\n\nhttps://float-middle.com/json-web-tokens-jwt-vs-sessions/\n\n\nHackerNews thread: https://news.ycombinator.com/item?id=11929267\n\n\n\n\nShaarli JWT Token\n\n\nJWT tokens are composed by three parts, separated by a dot \n.\n and encoded in base64:\n\n\n[header].[payload].[signature]\n\n\n\n\nHeader\n\n\nShaarli only allow one hash algorithm, so the header will always be the same:\n\n\n{\n    \"typ\": \"JWT\",\n    \"alg\": \"HS512\"\n}\n\n\n\n\nEncoded in base64, it gives:\n\n\newogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==\n\n\n\n\nPayload\n\n\nValidity duration\n\n\nTo avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key \niat\n (issued at). This token will be accepted during 9 minutes.\n\n\n{\n    \"iat\": 1468663519\n}\n\n\n\n\nSee \nRFC reference\n.\n\n\nSignature\n\n\nThe signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot \n.\n, hashed in SHA512 with the API secret available in Shaarli administration page.\n\n\nSignature example with PHP:\n\n\n$content = base64_encode($header) . '.' . base64_encode($payload);\n$signature = hash_hmac('sha512', $content, $secret);\n\n\n\n\nComplete example\n\n\nPHP\n\n\nfunction generateToken($secret) {\n    $header = base64_encode('{\n        \"typ\": \"JWT\",\n        \"alg\": \"HS512\"\n    }');\n    $payload = base64_encode('{\n        \"iat\": '. time() .'\n    }');\n    $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);\n    return $header .'.'. $payload .'.'. $signature;\n}\n\n$secret = 'mysecret';\n$token = generateToken($secret);\necho $token;\n\n\n\n\n\n\newogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68\n\n\n\n\n$options = [\n    'http' => [\n        'method' => 'GET',\n        'jwt' => $token,\n    ],\n];\n$context = stream_context_create($options);\nfile_get_contents($apiEndpoint, false, $context);",
            "title": "REST API"
        },
        {
            "location": "/REST-API/#usage",
            "text": "See the  REST API documentation .",
            "title": "Usage"
        },
        {
            "location": "/REST-API/#authentication",
            "text": "All requests to Shaarli's API must include a JWT token to verify their authenticity.  This token has to be included as an HTTP header called  Authentication: Bearer <jwt token> .  JWT resources :   jwt.io  (including a list of client per language).  RFC : https://tools.ietf.org/html/rfc7519  https://float-middle.com/json-web-tokens-jwt-vs-sessions/  HackerNews thread: https://news.ycombinator.com/item?id=11929267",
            "title": "Authentication"
        },
        {
            "location": "/REST-API/#shaarli-jwt-token",
            "text": "JWT tokens are composed by three parts, separated by a dot  .  and encoded in base64:  [header].[payload].[signature]",
            "title": "Shaarli JWT Token"
        },
        {
            "location": "/REST-API/#header",
            "text": "Shaarli only allow one hash algorithm, so the header will always be the same:  {\n    \"typ\": \"JWT\",\n    \"alg\": \"HS512\"\n}  Encoded in base64, it gives:  ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==",
            "title": "Header"
        },
        {
            "location": "/REST-API/#payload",
            "text": "Validity duration  To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key  iat  (issued at). This token will be accepted during 9 minutes.  {\n    \"iat\": 1468663519\n}  See  RFC reference .",
            "title": "Payload"
        },
        {
            "location": "/REST-API/#signature",
            "text": "The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot  . , hashed in SHA512 with the API secret available in Shaarli administration page.  Signature example with PHP:  $content = base64_encode($header) . '.' . base64_encode($payload);\n$signature = hash_hmac('sha512', $content, $secret);",
            "title": "Signature"
        },
        {
            "location": "/REST-API/#complete-example",
            "text": "",
            "title": "Complete example"
        },
        {
            "location": "/REST-API/#php",
            "text": "function generateToken($secret) {\n    $header = base64_encode('{\n        \"typ\": \"JWT\",\n        \"alg\": \"HS512\"\n    }');\n    $payload = base64_encode('{\n        \"iat\": '. time() .'\n    }');\n    $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);\n    return $header .'.'. $payload .'.'. $signature;\n}\n\n$secret = 'mysecret';\n$token = generateToken($secret);\necho $token;   ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68   $options = [\n    'http' => [\n        'method' => 'GET',\n        'jwt' => $token,\n    ],\n];\n$context = stream_context_create($options);\nfile_get_contents($apiEndpoint, false, $context);",
            "title": "PHP"
        },
        {
            "location": "/Backup,-restore,-import-and-export/",
            "text": "Backup and restore the datastore file\n\n\nExport links as...\n\n\nImport links from...\n\n\nImport Shaarli links to Firefox\n\n\n\n\n\n\nBackup and restore the datastore file\n\n\nBackup the file \ndata/datastore.php\n (by FTP or SSH). Restore by putting the file back in place.\n\n\nExample command:\n\n\nrsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php\n\n\n\n\nExport links as...\n\n\nTo export links as an HTML file, under \nTools > Export\n, choose:\n- \nExport all\n to export both public and private links\n- \nExport public\n to export public links only\n- \nExport private\n to export private links only\n\n\nRestore by using the \nImport\n feature.\n* This can be done using the \nshaarchiver\n tool.\n\n\nExample command: \n\n\n./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all\n\n\n\n\nImport links from...\n\n\nDiigo\n\n\nIf you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)\n\n\nMister Wong\n\n\nSee \nthis issue\n for import tweaks.\n\n\nSemanticScuttle\n\n\nTo correctly import the tags from a \nSemanticScuttle\n HTML export, edit the HTML file before importing and replace all occurences of \ntags=\n (lowercase) to \nTAGS=\n (uppercase).\n\n\nScuttle\n\n\nShaarli cannot import data directly from \nScuttle\n. However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.\n\n\nImport Shaarli links to Firefox\n\n\n\n\nExport your Shaarli links as described above.\n\n\nFor compatibility reasons, check \nPrepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)\n\n\nIn Firefox, open the bookmark manager (not the sidebar! \nBookmarks menu > Show all bookmarks\n or \nCtrl+Shift+B\n)\n\n\nSelect \nImport and Backup > Import bookmarks in HTML format\n\n\n\n\nYour bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. \"Self\" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.\n\n\nYou may be interested in these Firefox addons to manage links imported from Shaarli\n\n\n\n\nBookmark Deduplicator\n - provides an easy way to deduplicate your bookmarks\n\n\nTagSieve\n - browse your bookmarks by their tags",
            "title": "Backup, restore, import and export"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#backup-and-restore-the-datastore-file",
            "text": "Backup the file  data/datastore.php  (by FTP or SSH). Restore by putting the file back in place.  Example command:  rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php",
            "title": "Backup and restore the datastore file"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#export-links-as",
            "text": "To export links as an HTML file, under  Tools > Export , choose:\n-  Export all  to export both public and private links\n-  Export public  to export public links only\n-  Export private  to export private links only  Restore by using the  Import  feature.\n* This can be done using the  shaarchiver  tool.  Example command:   ./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all",
            "title": "Export links as..."
        },
        {
            "location": "/Backup,-restore,-import-and-export/#import-links-from",
            "text": "",
            "title": "Import links from..."
        },
        {
            "location": "/Backup,-restore,-import-and-export/#diigo",
            "text": "If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)",
            "title": "Diigo"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#mister-wong",
            "text": "See  this issue  for import tweaks.",
            "title": "Mister Wong"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#semanticscuttle",
            "text": "To correctly import the tags from a  SemanticScuttle  HTML export, edit the HTML file before importing and replace all occurences of  tags=  (lowercase) to  TAGS=  (uppercase).",
            "title": "SemanticScuttle"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#scuttle",
            "text": "Shaarli cannot import data directly from  Scuttle . However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.",
            "title": "Scuttle"
        },
        {
            "location": "/Backup,-restore,-import-and-export/#import-shaarli-links-to-firefox",
            "text": "Export your Shaarli links as described above.  For compatibility reasons, check  Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)  In Firefox, open the bookmark manager (not the sidebar!  Bookmarks menu > Show all bookmarks  or  Ctrl+Shift+B )  Select  Import and Backup > Import bookmarks in HTML format   Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. \"Self\" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.  You may be interested in these Firefox addons to manage links imported from Shaarli   Bookmark Deduplicator  - provides an easy way to deduplicate your bookmarks  TagSieve  - browse your bookmarks by their tags",
            "title": "Import Shaarli links to Firefox"
        },
        {
            "location": "/Various-hacks/",
            "text": "Decode datastore content\n\n\nTo display the array representing the data saved in \ndata/datastore.php\n, use the following snippet:\n\n\n$data = \"tZNdb9MwFIb... <Commented content inside datastore.php>\";\n$out = unserialize(gzinflate(base64_decode($data)));\necho \"<pre>\"; // Pretty printing is love, pretty printing is life\nprint_r($out);\necho \"</pre>\";\nexit;\n\n\n\n\nThis will output the internal representation of the datastore, \"unobfuscated\" (if this can really be considered obfuscation).\n\n\nAlternatively, you can transform to JSON format (and pretty-print if you have \njq\n installed):\n\n\nphp -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace(\"!.*/\\* (.+) \\*/.*!\", \"$1\", file_get_contents(\"data/datastore.php\")))))));' | jq .\n\n\n\n\nChanging the timestamp for a shaare\n\n\n\n\nLook for \n<input type=\"hidden\" name=\"lf_linkdate\" value=\"{$link.linkdate}\">\n in \ntpl/editlink.tpl\n (line 14)\n\n\nReplace \ntype=\"hidden\"\n with \ntype=\"text\"\n from this line\n\n\nA new date/time field becomes available in the edit/new link dialog.\n\n\nYou can set the timestamp manually by entering it in the format \nYYYMMDD_HHMMS\n.\n\n\n\n\nSee also\n\n\n\n\nAdd a new custom field to shaares (example patch)\n\n\nDownload CSS styles for shaarlis listed in an opml file\n\n\nCopy an existing Shaarli installation over SSH, and serve it locally\n\n\nCreate multiple Shaarli instances, generate an HTML index of them",
            "title": "Various hacks"
        },
        {
            "location": "/Various-hacks/#decode-datastore-content",
            "text": "To display the array representing the data saved in  data/datastore.php , use the following snippet:  $data = \"tZNdb9MwFIb... <Commented content inside datastore.php>\";\n$out = unserialize(gzinflate(base64_decode($data)));\necho \"<pre>\"; // Pretty printing is love, pretty printing is life\nprint_r($out);\necho \"</pre>\";\nexit;  This will output the internal representation of the datastore, \"unobfuscated\" (if this can really be considered obfuscation).  Alternatively, you can transform to JSON format (and pretty-print if you have  jq  installed):  php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace(\"!.*/\\* (.+) \\*/.*!\", \"$1\", file_get_contents(\"data/datastore.php\")))))));' | jq .",
            "title": "Decode datastore content"
        },
        {
            "location": "/Various-hacks/#changing-the-timestamp-for-a-shaare",
            "text": "Look for  <input type=\"hidden\" name=\"lf_linkdate\" value=\"{$link.linkdate}\">  in  tpl/editlink.tpl  (line 14)  Replace  type=\"hidden\"  with  type=\"text\"  from this line  A new date/time field becomes available in the edit/new link dialog.  You can set the timestamp manually by entering it in the format  YYYMMDD_HHMMS .",
            "title": "Changing the timestamp for a shaare"
        },
        {
            "location": "/Various-hacks/#see-also",
            "text": "Add a new custom field to shaares (example patch)  Download CSS styles for shaarlis listed in an opml file  Copy an existing Shaarli installation over SSH, and serve it locally  Create multiple Shaarli instances, generate an HTML index of them",
            "title": "See also"
        },
        {
            "location": "/Troubleshooting/",
            "text": "Troubleshooting\n\n\nBrowser\n\n\nRedirection issues (HTTP Referer)\n\n\nDepending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.\n\n\nSee:\n- \nHTTP referer\n (Wikipedia)\n- \nImprove online privacy by controlling referrer information\n\n- \nBetter security, privacy and anonymity in Firefox\n\n\nFirefox HTTP Referer options\n\n\nHTTP settings are available by browsing \nabout:config\n, here are the available settings and their values.\n\n\nnetwork.http.sendRefererHeader\n - determines when to send the Referer HTTP header\n- 0: Never send the referring URL\n    - not recommended, may break some sites\n- 1: Send only on clicked links\n- 2 (default): Send for links and images\n\n\nnetwork.http.referer.XOriginPolicy\n - Cross-domain origin policy\n- 0 (default): Always send\n- 1: Send if base domains match\n- 2: Send if hosts match\n\n\nnetwork.http.referer.spoofSource\n - Referer spoofing (~faking)\n- false (default): real referer\n- true: spoof referer (use target URI as referer)\n  - known to break some functionality in Shaarli\n\n\nnetwork.http.referer.trimmingPolicy\n - trim the URI not to send a full Referer\n- 0 (default): send full URI\n- 1: scheme+host+port+path\n- 2: scheme+host+port\n\n\nFirefox, localhost and redirections\n\n\nlocalhost\n is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.\n\n\nTo solve this, assign a local domain to your host, e.g.\n\n\n127.0.0.1 localhost desktop localhost.lan\n::1       localhost desktop localhost.lan\n\n\n\n\nand browse Shaarli at http://localhost.lan/.\n\n\nRelated threads:\n- \nWhat is localhost.localdomain for?\n\n- \nStop returning to the first page after editing a bookmark from another page\n\n\nLogin\n\n\nI forgot my password!\n\n\nDelete the file \ndata/config.php\n and display the page again. You will be asked for a new login/password.\n\n\nI'm locked out - Login bruteforce protection\n\n\nLogin form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.\n\n\nTo remove the current IP bans, delete the file \ndata/ipbans.php\n\n\nList of all login attempts\n\n\nThe file \ndata/log.txt\n shows all logins (successful or failed) and bans/lifted bans.\nSearch for \nfailed\n in this file to look for unauthorized login attempts.\n\n\nHosting problems\n\n\nOld PHP versions\n\n\n\n\nOn \nfree.fr\n : free.fr now support php 5.6.x(\nlink\n)and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a \nsessions\n directory and a \n.htaccess\n file containing:\n\n\n\n\n<IfDefine Free>\nphp56 1\n</IfDefine>\n\n\n\n\n\n\nIf you have an error such as: \nParse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx\n, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to \n.php5\n\n\nOn \n1and1\n : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).\n\n\nIf you have the error \nWarning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /\u2026/index.php on line xxx\n, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:\n\n\n\n\n//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.\n// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html \n//if (strpos($status,'200 OK')) $title=html_extract_title($data);\n\n\n\n\n\n\nOn hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.\n\n\nOn \nlost-oasis\n, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : \n<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>\n. To fix this, remove this message from \nphp-include/prepend.php\n\n\n\n\nDates are not properly formatted\n\n\nShaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )\n\n\nProblems on CentOS servers\n\n\nOn \nCentOS\n/RedHat derivatives, you may need to install the \nphp-mbstring\n package.\n\n\nMy session expires! I can't stay logged in\n\n\nThis can be caused by several things:\n\n\n\n\nYour php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a  \nsession\n directory on the root of your website.) You may need to create the session directory of set it up.\n\n\nMost hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the \nsessions\n subdirectory and add \nini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');\n. Make sure this directory is not browsable !)\n\n\nIf your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).\n\n\nSome browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey\u2026). Try disabling those.\n\n\nYou may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.\n\n\nIf you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.\n\n\n\n\nSessions do not seem to work correctly on your server\n\n\nFollow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have \nno dots\n in the hostname (e.g. \nlocalhost\n or \nhttp://my-webserver/shaarli/\n), some browsers will not store cookies at all (this respects the \nHTTP cookie specification\n).\n\n\npubsubhubbub support\n\n\nDownload \npublisher.php\n at the root of your Shaarli installation and set \n$GLOBALS['config']['PUBSUBHUB_URL']\n in your \nconfig.php",
            "title": "Troubleshooting"
        },
        {
            "location": "/Troubleshooting/#troubleshooting",
            "text": "",
            "title": "Troubleshooting"
        },
        {
            "location": "/Troubleshooting/#browser",
            "text": "",
            "title": "Browser"
        },
        {
            "location": "/Troubleshooting/#redirection-issues-http-referer",
            "text": "Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.  See:\n-  HTTP referer  (Wikipedia)\n-  Improve online privacy by controlling referrer information \n-  Better security, privacy and anonymity in Firefox",
            "title": "Redirection issues (HTTP Referer)"
        },
        {
            "location": "/Troubleshooting/#firefox-http-referer-options",
            "text": "HTTP settings are available by browsing  about:config , here are the available settings and their values.  network.http.sendRefererHeader  - determines when to send the Referer HTTP header\n- 0: Never send the referring URL\n    - not recommended, may break some sites\n- 1: Send only on clicked links\n- 2 (default): Send for links and images  network.http.referer.XOriginPolicy  - Cross-domain origin policy\n- 0 (default): Always send\n- 1: Send if base domains match\n- 2: Send if hosts match  network.http.referer.spoofSource  - Referer spoofing (~faking)\n- false (default): real referer\n- true: spoof referer (use target URI as referer)\n  - known to break some functionality in Shaarli  network.http.referer.trimmingPolicy  - trim the URI not to send a full Referer\n- 0 (default): send full URI\n- 1: scheme+host+port+path\n- 2: scheme+host+port",
            "title": "Firefox HTTP Referer options"
        },
        {
            "location": "/Troubleshooting/#firefox-localhost-and-redirections",
            "text": "localhost  is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.  To solve this, assign a local domain to your host, e.g.  127.0.0.1 localhost desktop localhost.lan\n::1       localhost desktop localhost.lan  and browse Shaarli at http://localhost.lan/.  Related threads:\n-  What is localhost.localdomain for? \n-  Stop returning to the first page after editing a bookmark from another page",
            "title": "Firefox, localhost and redirections"
        },
        {
            "location": "/Troubleshooting/#login",
            "text": "",
            "title": "Login"
        },
        {
            "location": "/Troubleshooting/#i-forgot-my-password",
            "text": "Delete the file  data/config.php  and display the page again. You will be asked for a new login/password.",
            "title": "I forgot my password!"
        },
        {
            "location": "/Troubleshooting/#im-locked-out-login-bruteforce-protection",
            "text": "Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.  To remove the current IP bans, delete the file  data/ipbans.php",
            "title": "I'm locked out - Login bruteforce protection"
        },
        {
            "location": "/Troubleshooting/#list-of-all-login-attempts",
            "text": "The file  data/log.txt  shows all logins (successful or failed) and bans/lifted bans.\nSearch for  failed  in this file to look for unauthorized login attempts.",
            "title": "List of all login attempts"
        },
        {
            "location": "/Troubleshooting/#hosting-problems",
            "text": "",
            "title": "Hosting problems"
        },
        {
            "location": "/Troubleshooting/#old-php-versions",
            "text": "On  free.fr  : free.fr now support php 5.6.x( link )and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a  sessions  directory and a  .htaccess  file containing:   <IfDefine Free>\nphp56 1\n</IfDefine>   If you have an error such as:  Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx , it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to  .php5  On  1and1  : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).  If you have the error  Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /\u2026/index.php on line xxx , it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:   //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.\n// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html \n//if (strpos($status,'200 OK')) $title=html_extract_title($data);   On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.  On  lost-oasis , RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed :  <? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?> . To fix this, remove this message from  php-include/prepend.php",
            "title": "Old PHP versions"
        },
        {
            "location": "/Troubleshooting/#dates-are-not-properly-formatted",
            "text": "Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )",
            "title": "Dates are not properly formatted"
        },
        {
            "location": "/Troubleshooting/#problems-on-centos-servers",
            "text": "On  CentOS /RedHat derivatives, you may need to install the  php-mbstring  package.",
            "title": "Problems on CentOS servers"
        },
        {
            "location": "/Troubleshooting/#my-session-expires-i-cant-stay-logged-in",
            "text": "This can be caused by several things:   Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a   session  directory on the root of your website.) You may need to create the session directory of set it up.  Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the  sessions  subdirectory and add  ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions'); . Make sure this directory is not browsable !)  If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).  Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey\u2026). Try disabling those.  You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.  If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.",
            "title": "My session expires! I can't stay logged in"
        },
        {
            "location": "/Troubleshooting/#sessions-do-not-seem-to-work-correctly-on-your-server",
            "text": "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 ).",
            "title": "Sessions do not seem to work correctly on your server"
        },
        {
            "location": "/Troubleshooting/#pubsubhubbub-support",
            "text": "Download  publisher.php  at the root of your Shaarli installation and set  $GLOBALS['config']['PUBSUBHUB_URL']  in your  config.php",
            "title": "pubsubhubbub support"
        },
        {
            "location": "/Development-guidelines/",
            "text": "Development guidelines\n\n\nPlease have a look at the following pages:\n- \nContributing to Shaarli\n\n- \nStatic analysis\n - patches should try to stick to the \nPHP Standard Recommendations\n (PSR), especially:\n    - \nPSR-1\n - Basic Coding Standard\n    - \nPSR-2\n - Coding Style Guide\n- \nUnit tests\n\n- \nGnuPG signature\n for tags/releases",
            "title": "Development guidelines"
        },
        {
            "location": "/Development-guidelines/#development-guidelines",
            "text": "Please have a look at the following pages:\n-  Contributing to Shaarli \n-  Static analysis  - patches should try to stick to the  PHP Standard Recommendations  (PSR), especially:\n    -  PSR-1  - Basic Coding Standard\n    -  PSR-2  - Coding Style Guide\n-  Unit tests \n-  GnuPG signature  for tags/releases",
            "title": "Development guidelines"
        },
        {
            "location": "/Continuous-integration-tools/",
            "text": "Local development\n\n\nA \nMakefile\n is available to perform project-related operations:\n- Documentation - generate a local HTML copy of the GitHub wiki\n- \nStatic analysis\n - check that the code is compliant to PHP conventions\n- \nUnit tests\n - ensure there are no regressions introduced by new commits\n\n\nAutomatic builds\n\n\nTravis CI\n is a Continuous Integration build server, that runs a build:\n- each time a commit is merged to the mainline (\nmaster\n branch)\n- each time a Pull Request is submitted or updated\n\n\nA build is composed of several jobs: one for each supported PHP version (see \nServer requirements\n).\n\n\nEach build job:\n- updates Composer\n- installs 3rd-party test dependencies with Composer\n- runs \nUnit tests\n\n\nAfter all jobs have finished, Travis returns the results to GitHub:\n- a status icon represents the result for the \nmaster\n branch: \n\n- Pull Requests are updated with the Travis result\n    - Green: all tests have passed\n    - Red: some tests failed\n    - Orange: tests are pending",
            "title": "Continuous integration tools"
        },
        {
            "location": "/Continuous-integration-tools/#local-development",
            "text": "A  Makefile  is available to perform project-related operations:\n- Documentation - generate a local HTML copy of the GitHub wiki\n-  Static analysis  - check that the code is compliant to PHP conventions\n-  Unit tests  - ensure there are no regressions introduced by new commits",
            "title": "Local development"
        },
        {
            "location": "/Continuous-integration-tools/#automatic-builds",
            "text": "Travis CI  is a Continuous Integration build server, that runs a build:\n- each time a commit is merged to the mainline ( master  branch)\n- each time a Pull Request is submitted or updated  A build is composed of several jobs: one for each supported PHP version (see  Server requirements ).  Each build job:\n- updates Composer\n- installs 3rd-party test dependencies with Composer\n- runs  Unit tests  After all jobs have finished, Travis returns the results to GitHub:\n- a status icon represents the result for the  master  branch:  \n- Pull Requests are updated with the Travis result\n    - Green: all tests have passed\n    - Red: some tests failed\n    - Orange: tests are pending",
            "title": "Automatic builds"
        },
        {
            "location": "/GnuPG-signature/",
            "text": "Introduction\n\n\nPGP and GPG\n\n\nGnu Privacy Guard\n (GnuPG) is an Open Source implementation of the \nPretty Good \nPrivacy\n (OpenPGP) specification. Its main purposes are digital authentication, \nsignature and encryption.\n\n\nIt is often used by the \nFLOSS\n community to verify:\n- Linux package signatures: Debian \nSecureApt\n, ArchLinux \nMaster \nKeys\n\n- \nSCM\n releases & maintainer identity\n\n\nTrust\n\n\nTo quote Phil Pennock (the author of the \nSKS\n key server - http://sks.spodhuis.org/):\n\n\n\n\nYou 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 \u201cobject level\u201d, via PGP 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.\n\n\n\n\nTrust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during \nkey signing parties\n, see:\n- \nThe Keysigning party HOWTO\n\n- \nWeb of trust\n\n\nGenerate a GPG key\n\n\n\n\nGenerating a GPG key for Git tagging\n (StackOverflow)\n\n\nGenerating a GPG key\n (GitHub)\n\n\n\n\ngpg - provide identity information\n\n\n$ gpg --gen-key\n\ngpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\n\nNote: Use \"gpg2 --full-gen-key\" for a full featured key generation dialog.\n\nGnuPG needs to construct a user ID to identify your key.\n\nReal name: Marvin the Paranoid Android\nEmail address: marvin@h2g2.net\nYou selected this USER-ID:\n    \"Marvin the Paranoid Android <marvin@h2g2.net>\"\n\nChange (N)ame, (E)mail, or (O)kay/(Q)uit? o\nWe need to generate a lot of random bytes. It is a good idea to perform\nsome other action (type on the keyboard, move the mouse, utilize the\ndisks) during the prime generation; this gives the random number\ngenerator a better chance to gain enough entropy.\n\n\n\n\ngpg - entropy interlude\n\n\nAt this point, you will:\n- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)\n- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step \nmay take some time\n \n\n\ngpg - key creation confirmation\n\n\ngpg: key A9D53A3E marked as ultimately trusted\npublic and secret key created and signed.\n\ngpg: checking the trustdb\ngpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model\ngpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u\npub   rsa2048/A9D53A3E 2015-07-31\n      Key fingerprint = AF2A 5381 E54B 2FD2 14C4  A9A3 0E35 ACA4 A9D5 3A3E\nuid       [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>\nsub   rsa2048/8C0EACF1 2015-07-31\n\n\n\n\ngpg - submit your public key to a PGP server (Optional)\n\n\n$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E\ngpg: sending key A9D53A3E to hkp server pgp.mit.edu\n\n\n\n\nCreate and push a GPG-signed tag\n\n\nSee \nRelease Shaarli\n.",
            "title": "GnuPG signature"
        },
        {
            "location": "/GnuPG-signature/#introduction",
            "text": "",
            "title": "Introduction"
        },
        {
            "location": "/GnuPG-signature/#pgp-and-gpg",
            "text": "Gnu Privacy Guard  (GnuPG) is an Open Source implementation of the  Pretty Good \nPrivacy  (OpenPGP) specification. Its main purposes are digital authentication, \nsignature and encryption.  It is often used by the  FLOSS  community to verify:\n- Linux package signatures: Debian  SecureApt , ArchLinux  Master \nKeys \n-  SCM  releases & maintainer identity",
            "title": "PGP and GPG"
        },
        {
            "location": "/GnuPG-signature/#trust",
            "text": "To quote Phil Pennock (the author of the  SKS  key server - http://sks.spodhuis.org/):   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 \u201cobject level\u201d, via PGP 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.   Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during  key signing parties , see:\n-  The Keysigning party HOWTO \n-  Web of trust",
            "title": "Trust"
        },
        {
            "location": "/GnuPG-signature/#generate-a-gpg-key",
            "text": "Generating a GPG key for Git tagging  (StackOverflow)  Generating a GPG key  (GitHub)",
            "title": "Generate a GPG key"
        },
        {
            "location": "/GnuPG-signature/#gpg-provide-identity-information",
            "text": "$ gpg --gen-key\n\ngpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\n\nNote: Use \"gpg2 --full-gen-key\" for a full featured key generation dialog.\n\nGnuPG needs to construct a user ID to identify your key.\n\nReal name: Marvin the Paranoid Android\nEmail address: marvin@h2g2.net\nYou selected this USER-ID:\n    \"Marvin the Paranoid Android <marvin@h2g2.net>\"\n\nChange (N)ame, (E)mail, or (O)kay/(Q)uit? o\nWe need to generate a lot of random bytes. It is a good idea to perform\nsome other action (type on the keyboard, move the mouse, utilize the\ndisks) during the prime generation; this gives the random number\ngenerator a better chance to gain enough entropy.",
            "title": "gpg - provide identity information"
        },
        {
            "location": "/GnuPG-signature/#gpg-entropy-interlude",
            "text": "At this point, you will:\n- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)\n- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step  may take some time",
            "title": "gpg - entropy interlude"
        },
        {
            "location": "/GnuPG-signature/#gpg-key-creation-confirmation",
            "text": "gpg: key A9D53A3E marked as ultimately trusted\npublic and secret key created and signed.\n\ngpg: checking the trustdb\ngpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model\ngpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u\npub   rsa2048/A9D53A3E 2015-07-31\n      Key fingerprint = AF2A 5381 E54B 2FD2 14C4  A9A3 0E35 ACA4 A9D5 3A3E\nuid       [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>\nsub   rsa2048/8C0EACF1 2015-07-31",
            "title": "gpg - key creation confirmation"
        },
        {
            "location": "/GnuPG-signature/#gpg-submit-your-public-key-to-a-pgp-server-optional",
            "text": "$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E\ngpg: sending key A9D53A3E to hkp server pgp.mit.edu",
            "title": "gpg - submit your public key to a PGP server (Optional)"
        },
        {
            "location": "/GnuPG-signature/#create-and-push-a-gpg-signed-tag",
            "text": "See  Release Shaarli .",
            "title": "Create and push a GPG-signed tag"
        },
        {
            "location": "/Coding-guidelines/",
            "text": "WIP\n\n\nThis topic is currently being discussed here:\n- \nFix coding style (static analysis)\n (#95)\n- \nContinuous Integration tools & features\n (#130)",
            "title": "Coding guidelines"
        },
        {
            "location": "/Coding-guidelines/#wip",
            "text": "This topic is currently being discussed here:\n-  Fix coding style (static analysis)  (#95)\n-  Continuous Integration tools & features  (#130)",
            "title": "WIP"
        },
        {
            "location": "/Directory-structure/",
            "text": "Here is the directory structure of Shaarli and the purpose of the different files:\n\n\n    index.php        # Main program\n    application/     # Shaarli classes\n        \u251c\u2500\u2500 LinkDB.php\n        \u2514\u2500\u2500 Utils.php\n    tests/       # Shaarli unitary & functional tests\n        \u251c\u2500\u2500 LinkDBTest.php\n        \u251c\u2500\u2500 utils  # utilities to ease testing\n        \u2502   \u2514\u2500\u2500 ReferenceLinkDB.php\n        \u2514\u2500\u2500 UtilsTest.php\n    COPYING          # Shaarli license\n    inc/             # static assets and 3rd party libraries\n        \u251c\u2500\u2500 awesomplete.*          # tags autocompletion library\n        \u251c\u2500\u2500 blazy.*                # picture wall lazy image loading library\n        \u251c\u2500\u2500 shaarli.css, reset.css # Shaarli stylesheet.\n        \u251c\u2500\u2500 qr.*                   # qr code generation library\n        \u2514\u2500\u2500rain.tpl.class.php      # RainTPL templating library\n    tpl/             # RainTPL templates for Shaarli. They are used to build the pages.\n    images/          # Images and icons used in Shaarli\n    data/            # data storage: bookmark database, configuration, logs, banlist\u2026\n        \u251c\u2500\u2500 config.php             # Shaarli configuration (login, password, timezone, title\u2026)\n        \u251c\u2500\u2500 datastore.php          # Your link database (compressed).\n        \u251c\u2500\u2500 ipban.php              # IP address ban system data\n        \u251c\u2500\u2500 lastupdatecheck.txt    # Update check timestamp file\n        \u2514\u2500\u2500log.txt                 # login/IPban log.\n    cache/           # thumbnails cache\n                     # This directory is automatically created. You can erase it anytime you want.\n    tmp/             # Temporary directory for compiled RainTPL templates.\n                     # This directory is automatically created. You can erase it anytime you want.",
            "title": "Directory structure"
        },
        {
            "location": "/3rd-party-libraries/",
            "text": "CSS\n\n\n\n\nYahoo UI \nCSS Reset\n\n\nresets default CSS properties for all HTML elements (overriding browsers' default values)\n\n\nensures custom CSS stylessheets will provide the same results on all browsers\n\n\n\n\n\n\n\n\nJavascript\n\n\n\n\nAwesomeplete\n (\nGitHub\n) - autocompletion in input forms\n\n\nbLazy\n (\nGitHub\n) - lazy loading for thumbnails\n\n\nqr.js\n (\nGitHub\n) - QR code generation\n\n\n\n\nPHP\n\n\n\n\nshaarli/netscape-bookmark-parser\n - Netscape bookmark parser\n\n\nRainTPL\n - HTML templating for PHP",
            "title": "3rd party libraries"
        },
        {
            "location": "/3rd-party-libraries/#css",
            "text": "Yahoo UI  CSS Reset  resets default CSS properties for all HTML elements (overriding browsers' default values)  ensures custom CSS stylessheets will provide the same results on all browsers",
            "title": "CSS"
        },
        {
            "location": "/3rd-party-libraries/#javascript",
            "text": "Awesomeplete  ( GitHub ) - autocompletion in input forms  bLazy  ( GitHub ) - lazy loading for thumbnails  qr.js  ( GitHub ) - QR code generation",
            "title": "Javascript"
        },
        {
            "location": "/3rd-party-libraries/#php",
            "text": "shaarli/netscape-bookmark-parser  - Netscape bookmark parser  RainTPL  - HTML templating for PHP",
            "title": "PHP"
        },
        {
            "location": "/Plugin-System/",
            "text": "I am a developer.\n Developer API.\n\n\nI am a template designer.\n Guide for template designer.\n\n\nDeveloper API\n\n\nWhat can I do with plugins?\n\n\nThe plugin system let you:\n\n\n\n\ninsert content into specific places across templates.\n\n\nalter data before templates rendering.\n\n\nalter data before saving new links.\n\n\n\n\nHow can I create a plugin for Shaarli?\n\n\nFirst, chose a plugin name, such as \ndemo_plugin\n.\n\n\nUnder \nplugin\n folder, create a folder named with your plugin name. Then create a \n.php file in that folder.\n\n\nYou should have the following tree view:\n\n\n| index.php\n| plugins/\n|---| demo_plugin/\n|   |---| demo_plugin.php\n\n\n\n\nPlugin initialization\n\n\nAt the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an \ninit()\n function to execute and run it if it exists. This function must be named this way, and takes the \nConfigManager\n as parameter.\n\n\n<plugin_name>_init($conf)\n\n\n\nThis function can be used to create initial data, load default settings, etc. But also to set \nplugin errors\n. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.\n\n\nUnderstanding hooks\n\n\nA plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.\n\n\nThese functions need to be named with this pattern:\n\n\nhook_<plugin_name>_<hook_name>($data, $conf)\n\n\n\n\nParameters:\n\n\n\n\ndata: see \n$data section\n\n\nconf: the \nConfigManager\n instance.\n\n\n\n\nFor exemple, if my plugin want to add data to the header, this function is needed:\n\n\nhook_demo_plugin_render_header\n\n\n\nIf this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.\n\n\nPlugin's data\n\n\nParameters\n\n\nEvery hook function has a \n$data\n parameter. Its content differs for each hooks.\n\n\nThis parameter needs to be returned every time\n, otherwise data is lost.\n\n\nreturn $data;\n\n\n\nFilling templates placeholder\n\n\nTemplate placeholders are displayed in template in specific places.\n\n\nRainTPL displays every element contained in the placeholder's array. These element can be added by plugins.\n\n\nFor example, let's add a value in the placeholder \ntop_placeholder\n which is displayed at the top of my page:\n\n\n$data['top_placeholder'][] = 'My content';\n# OR\narray_push($data['top_placeholder'], 'My', 'content');\n\nreturn $data;\n\n\n\n\nData manipulation\n\n\nWhen a page is displayed, every variable send to the template engine is passed to plugins before that in \n$data\n.\n\n\nThe data contained by this array can be altered before template rendering.\n\n\nFor exemple, in linklist, it is possible to alter every title:\n\n\n// mind the reference if you want $data to be altered\nforeach ($data['links'] as &$value) {\n    // String reverse every title.\n    $value['title'] = strrev($value['title']);\n}\n\nreturn $data;\n\n\n\n\nMetadata\n\n\nEvery plugin needs a \n<plugin_name>.meta\n file, which is in fact an \n.ini\n file (\nKEY=\"VALUE\"\n), to be listed in plugin administration.\n\n\nEach file contain two keys:\n\n\n\n\ndescription\n: plugin description\n\n\nparameters\n: user parameter names, separated by a \n;\n.\n\n\nparameter.<PARAMETER_NAME>\n: add a text description the specified parameter.\n\n\n\n\n\n\nNote: In PHP, \nparse_ini_file()\n seems to want strings to be between by quotes \n\"\n in the ini file.\n\n\n\n\nIt's not working!\n\n\nUse \ndemo_plugin\n as a functional example. It covers most of the plugin system features.\n\n\nIf it's still not working, please \nopen an issue\n.\n\n\nHooks\n\n\n\n\n\n\n\n\nHooks\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nrender_header\n\n\nAllow plugin to add content in page headers.\n\n\n\n\n\n\nrender_includes\n\n\nAllow plugin to include their own CSS files.\n\n\n\n\n\n\nrender_footer\n\n\nAllow plugin to add content in page footer and include their own JS files.\n\n\n\n\n\n\nrender_linklist\n\n\nIt allows to add content at the begining and end of the page, after every link displayed and to alter link data.\n\n\n\n\n\n\nrender_editlink\n\n\nAllow to add fields in the form, or display elements.\n\n\n\n\n\n\nrender_tools\n\n\nAllow to add content at the end of the page.\n\n\n\n\n\n\nrender_picwall\n\n\nAllow to add content at the top and bottom of the page.\n\n\n\n\n\n\nrender_tagcloud\n\n\nAllow to add content at the top and bottom of the page, and after all tags.\n\n\n\n\n\n\nrender_taglist\n\n\nAllow to add content at the top and bottom of the page, and after all tags.\n\n\n\n\n\n\nrender_daily\n\n\nAllow to add content at the top and bottom of the page, the bottom of each link and to alter data.\n\n\n\n\n\n\nrender_feed\n\n\nAllow to do add tags in RSS and ATOM feeds.\n\n\n\n\n\n\nsave_link\n\n\nAllow to alter the link being saved in the datastore.\n\n\n\n\n\n\ndelete_link\n\n\nAllow to do an action before a link is deleted from the datastore.\n\n\n\n\n\n\n\n\nrender_header\n\n\nTriggered on every page.\n\n\nAllow plugin to add content in page headers.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_PAGE_\n: current target page (eg: \nlinklist\n, \npicwall\n, etc.).\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\nbuttons_toolbar\n: after the list of buttons in the header.\n\n\n\n\n\n\n\n\nfields_toolbar\n: after search fields in the header.\n\n\n\n\n\n\nNote: This will only be called in linklist.\n\n\n\n\n\n\nrender_includes\n\n\nTriggered on every page.\n\n\nAllow plugin to include their own CSS files.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_PAGE_\n: current target page (eg: \nlinklist\n, \npicwall\n, etc.).\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\ncss_files\n: called after loading default CSS.\n\n\n\n\n\n\nNote: only add the path of the CSS file. E.g: \nplugins/demo_plugin/custom_demo.css\n.\n\n\n\n\nrender_footer\n\n\nTriggered on every page.\n\n\nAllow plugin to add content in page footer and include their own JS files.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_PAGE_\n: current target page (eg: \nlinklist\n, \npicwall\n, etc.).\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\ntext\n: called after the end of the footer text.\n\n\nendofpage\n: called at the end of the page.\n\n\n\n\n\n\n\n\njs_files\n: called at the end of the page, to include custom JS scripts.\n\n\n\n\n\n\nNote: only add the path of the JS file. E.g: \nplugins/demo_plugin/custom_demo.js\n.\n\n\n\n\nrender_linklist\n\n\nTriggered when \nlinklist\n is displayed (list of links, permalink, search, tag filtered, etc.).\n\n\nIt allows to add content at the begining and end of the page, after every link displayed and to alter link data.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\nAll templates data, including links.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\naction_plugin\n: next to the button \"private only\" at the top and bottom of the page.\n\n\n\n\n\n\n\n\nlink_plugin\n: for every link, between permalink and link URL.\n\n\n\n\n\n\n\n\nplugin_start_zone\n: before displaying the template content.\n\n\n\n\n\n\n\n\nplugin_end_zone\n: after displaying the template content.\n\n\n\n\n\n\nrender_editlink\n\n\nTriggered when the link edition form is displayed.\n\n\nAllow to add fields in the form, or display elements.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\nAll templates data.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\nedit_link_plugin\n: after tags field.\n\n\n\n\n\n\nrender_tools\n\n\nTriggered when the \"tools\" page is displayed.\n\n\nAllow to add content at the end of the page.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\nAll templates data.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\ntools_plugin\n: at the end of the page.\n\n\n\n\n\n\nrender_picwall\n\n\nTriggered when picwall is displayed.\n\n\nAllow to add content at the top and bottom of the page.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\nAll templates data.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\n\n\nplugin_start_zone\n: before displaying the template content.\n\n\n\n\n\n\nplugin_end_zone\n: after displaying the template content.\n\n\n\n\n\n\n\n\nrender_tagcloud\n\n\nTriggered when tagcloud is displayed.\n\n\nAllow to add content at the top and bottom of the page.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\nAll templates data.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\n\n\nplugin_start_zone\n: before displaying the template content.\n\n\n\n\n\n\nplugin_end_zone\n: after displaying the template content.\n\n\n\n\n\n\nFor each tag, the following placeholder can be used:\n\n\n\n\ntag_plugin\n: after each tag\n\n\n\n\n\n\nrender_taglist\n\n\nTriggered when taglist is displayed.\n\n\nAllow to add content at the top and bottom of the page.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\nAll templates data.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\n\n\nplugin_start_zone\n: before displaying the template content.\n\n\n\n\n\n\nplugin_end_zone\n: after displaying the template content.\n\n\n\n\n\n\nFor each tag, the following placeholder can be used:\n\n\n\n\ntag_plugin\n: after each tag\n\n\n\n\nrender_daily\n\n\nTriggered when tagcloud is displayed.\n\n\nAllow to add content at the top and bottom of the page, the bottom of each link and to alter data.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\nAll templates data, including links.\n\n\n\n\nTemplate placeholders\n\n\nItems can be displayed in templates by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\nlink_plugin\n: used at bottom of each link.\n\n\n\n\n\n\n\n\n\n\nplugin_start_zone\n: before displaying the template content.\n\n\n\n\n\n\nplugin_end_zone\n: after displaying the template content.\n\n\n\n\n\n\nrender_feed\n\n\nTriggered when the ATOM or RSS feed is displayed.\n\n\nAllow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.\n\n\nData\n\n\n$data\n is an array containing:\n\n\n\n\n_LOGGEDIN_\n: true if user is logged in, false otherwise.\n\n\n_PAGE_\n: containing either \nrss\n or \natom\n.\n\n\nAll templates data, including links.\n\n\n\n\nTemplate placeholders\n\n\nTags can be added in feeds by adding an entry in \n$data['<placeholder>']\n array.\n\n\nList of placeholders:\n\n\n\n\nfeed_plugins_header\n: used as a header tag in the feed.\n\n\n\n\nFor each links:\n\n\n\n\nfeed_plugins\n: additional tag for every link entry.\n\n\n\n\nsave_link\n\n\nTriggered when a link is save (new link or edit).\n\n\nAllow to alter the link being saved in the datastore.\n\n\nData\n\n\n$data\n is an array containing the link being saved:\n\n\n\n\nid\n\n\ntitle\n\n\nurl\n\n\nshorturl\n\n\ndescription\n\n\nprivate\n\n\ntags\n\n\ncreated\n\n\nupdated\n\n\n\n\ndelete_link\n\n\nTriggered when a link is deleted.\n\n\nAllow to execute any action before the link is actually removed from the datastore\n\n\nData\n\n\n$data\n is an array containing the link being saved:\n\n\n\n\nid\n\n\ntitle\n\n\nurl\n\n\nshorturl\n\n\ndescription\n\n\nprivate\n\n\ntags\n\n\ncreated\n\n\nupdated\n\n\n\n\nGuide for template designer\n\n\nPlugin administration\n\n\nYour theme must include a plugin administration page: \npluginsadmin.html\n.\n\n\n\n\nNote: repo's template link needs to be added when the PR is merged.\n\n\n\n\nUse the default one as an example.\n\n\nAside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include \nplugin_admin.js\n, only if:\n\n\n\n\nyou're using a table.\n\n\nyou call orderUp() and orderUp() onclick on arrows.\n\n\nyou add data-line and data-order to your rows.\n\n\n\n\nOtherwise, you can use your own JS as long as this field is send by the form:\n\n\n\n\nPlaceholder system\n\n\nIn order to make plugins work with every custom themes, you need to add variable placeholder in your templates. \n\n\nIt's a RainTPL loop like this:\n\n\n{loop=\"$plugin_variable\"}\n    {$value}\n{/loop}\n\n\n\nYou should enable \ndemo_plugin\n for testing purpose, since it uses every placeholder available.\n\n\nList of placeholders\n\n\npage.header.html\n\n\nAt the end of the menu:\n\n\n{loop=\"$plugins_header.buttons_toolbar\"}\n    {$value}\n{/loop}\n\n\n\nAt the end of file, before clearing floating blocks:\n\n\n{if=\"!empty($plugin_errors) && isLoggedIn()\"}\n    <ul class=\"errors\">\n        {loop=\"plugin_errors\"}\n            <li>{$value}</li>\n        {/loop}\n    </ul>\n{/if}\n\n\n\nincludes.html\n\n\nAt the end of the file:\n\n\n{loop=\"$plugins_includes.css_files\"}\n<link type=\"text/css\" rel=\"stylesheet\" href=\"{$value}#\"/>\n{/loop}\n\n\n\n\npage.footer.html\n\n\nAt the end of your footer notes:\n\n\n{loop=\"$plugins_footer.text\"}\n     {$value}\n{/loop}\n\n\n\n\nAt the end of file:\n\n\n{loop=\"$plugins_footer.js_files\"}\n     <script src=\"{$value}#\"></script>\n{/loop}\n\n\n\n\nlinklist.html\n\n\nAfter search fields:\n\n\n{loop=\"$plugins_header.fields_toolbar\"}\n     {$value}\n{/loop}\n\n\n\n\nBefore displaying the link list (after paging):\n\n\n{loop=\"$plugin_start_zone\"}\n     {$value}\n{/loop}\n\n\n\n\nFor every links (icons):\n\n\n{loop=\"$value.link_plugin\"}\n    <span>{$value}</span>\n{/loop}\n\n\n\n\nBefore end paging:\n\n\n{loop=\"$plugin_end_zone\"}\n     {$value}\n{/loop}\n\n\n\n\nlinklist.paging.html\n\n\nAfter the \"private only\" icon:\n\n\n{loop=\"$action_plugin\"}\n     {$value}\n{/loop}\n\n\n\n\neditlink.html\n\n\nAfter tags field:\n\n\n{loop=\"$edit_link_plugin\"}\n     {$value}\n{/loop}\n\n\n\n\ntools.html\n\n\nAfter the last tool:\n\n\n{loop=\"$tools_plugin\"}\n     {$value}\n{/loop}\n\n\n\n\npicwall.html\n\n\nTop:\n\n\n<div id=\"plugin_zone_start_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_start_zone\"}\n        {$value}\n    {/loop}\n</div>\n\n\n\n\nBottom:\n\n\n<div id=\"plugin_zone_end_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_end_zone\"}\n        {$value}\n    {/loop}\n</div>\n\n\n\n\ntagcloud.html\n\n\nTop:\n\n\n   <div id=\"plugin_zone_start_tagcloud\" class=\"plugin_zone\">\n        {loop=\"$plugin_start_zone\"}\n            {$value}\n        {/loop}\n    </div>\n\n\n\n\nBottom:\n\n\n    <div id=\"plugin_zone_end_tagcloud\" class=\"plugin_zone\">\n        {loop=\"$plugin_end_zone\"}\n            {$value}\n        {/loop}\n    </div>\n\n\n\n\ndaily.html\n\n\nTop:\n\n\n<div id=\"plugin_zone_start_picwall\" class=\"plugin_zone\">\n     {loop=\"$plugin_start_zone\"}\n         {$value}\n     {/loop}\n</div>\n\n\n\n\nAfter every link:\n\n\n<div class=\"dailyEntryFooter\">\n     {loop=\"$link.link_plugin\"}\n          {$value}\n     {/loop}\n</div>\n\n\n\n\nBottom:\n\n\n<div id=\"plugin_zone_end_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_end_zone\"}\n        {$value}\n    {/loop}\n</div>\n\n\n\n\nfeed.atom.xml\n and \nfeed.rss.xml\n:\n\n\nIn headers tags section:\n\n\n{loop=\"$feed_plugins_header\"}\n  {$value}\n{/loop}\n\n\n\n\nAfter each entry:\n\n\n{loop=\"$value.feed_plugins\"}\n  {$value}\n{/loop}",
            "title": "Plugin System"
        },
        {
            "location": "/Plugin-System/#developer-api",
            "text": "",
            "title": "Developer API"
        },
        {
            "location": "/Plugin-System/#what-can-i-do-with-plugins",
            "text": "The plugin system let you:   insert content into specific places across templates.  alter data before templates rendering.  alter data before saving new links.",
            "title": "What can I do with plugins?"
        },
        {
            "location": "/Plugin-System/#how-can-i-create-a-plugin-for-shaarli",
            "text": "First, chose a plugin name, such as  demo_plugin .  Under  plugin  folder, create a folder named with your plugin name. Then create a  .php file in that folder.  You should have the following tree view:  | index.php\n| plugins/\n|---| demo_plugin/\n|   |---| demo_plugin.php",
            "title": "How can I create a plugin for Shaarli?"
        },
        {
            "location": "/Plugin-System/#plugin-initialization",
            "text": "At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an  init()  function 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.",
            "title": "Plugin initialization"
        },
        {
            "location": "/Plugin-System/#understanding-hooks",
            "text": "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  conf: the  ConfigManager  instance.   For exemple, 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.",
            "title": "Understanding hooks"
        },
        {
            "location": "/Plugin-System/#plugins-data",
            "text": "",
            "title": "Plugin's data"
        },
        {
            "location": "/Plugin-System/#parameters",
            "text": "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;",
            "title": "Parameters"
        },
        {
            "location": "/Plugin-System/#filling-templates-placeholder",
            "text": "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:  $data['top_placeholder'][] = 'My content';\n# OR\narray_push($data['top_placeholder'], 'My', 'content');\n\nreturn $data;",
            "title": "Filling templates placeholder"
        },
        {
            "location": "/Plugin-System/#data-manipulation",
            "text": "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 exemple, in linklist, it is possible to alter every title:  // mind the reference if you want $data to be altered\nforeach ($data['links'] as &$value) {\n    // String reverse every title.\n    $value['title'] = strrev($value['title']);\n}\n\nreturn $data;",
            "title": "Data manipulation"
        },
        {
            "location": "/Plugin-System/#metadata",
            "text": "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.",
            "title": "Metadata"
        },
        {
            "location": "/Plugin-System/#its-not-working",
            "text": "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 .",
            "title": "It's not working!"
        },
        {
            "location": "/Plugin-System/#hooks",
            "text": "Hooks  Description      render_header  Allow plugin to add content in page headers.    render_includes  Allow plugin to include their own CSS files.    render_footer  Allow plugin to add content in page footer and include their own JS files.    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  Allow to add fields in the form, or display elements.    render_tools  Allow to add content at the end of the page.    render_picwall  Allow to add content at the top and bottom of the page.    render_tagcloud  Allow to add content at the top and bottom of the page, and after all tags.    render_taglist  Allow to add content at the top and bottom of the page, and after all tags.    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  Allow to do add tags in RSS and ATOM feeds.    save_link  Allow to alter the link being saved in the datastore.    delete_link  Allow to do an action before a link is deleted from the datastore.",
            "title": "Hooks"
        },
        {
            "location": "/Plugin-System/#render_header",
            "text": "Triggered on every page.  Allow plugin to add content in page headers.",
            "title": "render_header"
        },
        {
            "location": "/Plugin-System/#data",
            "text": "$data  is an array containing:   _PAGE_ : current target page (eg:  linklist ,  picwall , etc.).  _LOGGEDIN_ : true if user is logged in, false otherwise.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_includes",
            "text": "Triggered on every page.  Allow plugin to include their own CSS files.",
            "title": "render_includes"
        },
        {
            "location": "/Plugin-System/#data_1",
            "text": "$data  is an array containing:   _PAGE_ : current target page (eg:  linklist ,  picwall , etc.).  _LOGGEDIN_ : true if user is logged in, false otherwise.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_1",
            "text": "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 .",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_footer",
            "text": "Triggered on every page.  Allow plugin to add content in page footer and include their own JS files.",
            "title": "render_footer"
        },
        {
            "location": "/Plugin-System/#data_2",
            "text": "$data  is an array containing:   _PAGE_ : current target page (eg:  linklist ,  picwall , etc.).  _LOGGEDIN_ : true if user is logged in, false otherwise.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_2",
            "text": "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 .",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_linklist",
            "text": "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.",
            "title": "render_linklist"
        },
        {
            "location": "/Plugin-System/#data_3",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  All templates data, including links.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_3",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_editlink",
            "text": "Triggered when the link edition form is displayed.  Allow to add fields in the form, or display elements.",
            "title": "render_editlink"
        },
        {
            "location": "/Plugin-System/#data_4",
            "text": "$data  is an array containing:   All templates data.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_4",
            "text": "Items can be displayed in templates by adding an entry in  $data['<placeholder>']  array.  List of placeholders:   edit_link_plugin : after tags field.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_tools",
            "text": "Triggered when the \"tools\" page is displayed.  Allow to add content at the end of the page.",
            "title": "render_tools"
        },
        {
            "location": "/Plugin-System/#data_5",
            "text": "$data  is an array containing:   All templates data.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_5",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_picwall",
            "text": "Triggered when picwall is displayed.  Allow to add content at the top and bottom of the page.",
            "title": "render_picwall"
        },
        {
            "location": "/Plugin-System/#data_6",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  All templates data.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_6",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_tagcloud",
            "text": "Triggered when tagcloud is displayed.  Allow to add content at the top and bottom of the page.",
            "title": "render_tagcloud"
        },
        {
            "location": "/Plugin-System/#data_7",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  All templates data.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_7",
            "text": "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",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_taglist",
            "text": "Triggered when taglist is displayed.  Allow to add content at the top and bottom of the page.",
            "title": "render_taglist"
        },
        {
            "location": "/Plugin-System/#data_8",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  All templates data.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_8",
            "text": "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",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_daily",
            "text": "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.",
            "title": "render_daily"
        },
        {
            "location": "/Plugin-System/#data_9",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  All templates data, including links.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_9",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#render_feed",
            "text": "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.",
            "title": "render_feed"
        },
        {
            "location": "/Plugin-System/#data_10",
            "text": "$data  is an array containing:   _LOGGEDIN_ : true if user is logged in, false otherwise.  _PAGE_ : containing either  rss  or  atom .  All templates data, including links.",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#template-placeholders_10",
            "text": "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.",
            "title": "Template placeholders"
        },
        {
            "location": "/Plugin-System/#save_link",
            "text": "Triggered when a link is save (new link or edit).  Allow to alter the link being saved in the datastore.",
            "title": "save_link"
        },
        {
            "location": "/Plugin-System/#data_11",
            "text": "$data  is an array containing the link being saved:   id  title  url  shorturl  description  private  tags  created  updated",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#delete_link",
            "text": "Triggered when a link is deleted.  Allow to execute any action before the link is actually removed from the datastore",
            "title": "delete_link"
        },
        {
            "location": "/Plugin-System/#data_12",
            "text": "$data  is an array containing the link being saved:   id  title  url  shorturl  description  private  tags  created  updated",
            "title": "Data"
        },
        {
            "location": "/Plugin-System/#guide-for-template-designer",
            "text": "",
            "title": "Guide for template designer"
        },
        {
            "location": "/Plugin-System/#plugin-administration",
            "text": "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:",
            "title": "Plugin administration"
        },
        {
            "location": "/Plugin-System/#placeholder-system",
            "text": "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\"}\n    {$value}\n{/loop}  You should enable  demo_plugin  for testing purpose, since it uses every placeholder available.",
            "title": "Placeholder system"
        },
        {
            "location": "/Plugin-System/#list-of-placeholders",
            "text": "page.header.html  At the end of the menu:  {loop=\"$plugins_header.buttons_toolbar\"}\n    {$value}\n{/loop}  At the end of file, before clearing floating blocks:  {if=\"!empty($plugin_errors) && isLoggedIn()\"}\n    <ul class=\"errors\">\n        {loop=\"plugin_errors\"}\n            <li>{$value}</li>\n        {/loop}\n    </ul>\n{/if}  includes.html  At the end of the file:  {loop=\"$plugins_includes.css_files\"}\n<link type=\"text/css\" rel=\"stylesheet\" href=\"{$value}#\"/>\n{/loop}  page.footer.html  At the end of your footer notes:  {loop=\"$plugins_footer.text\"}\n     {$value}\n{/loop}  At the end of file:  {loop=\"$plugins_footer.js_files\"}\n     <script src=\"{$value}#\"></script>\n{/loop}  linklist.html  After search fields:  {loop=\"$plugins_header.fields_toolbar\"}\n     {$value}\n{/loop}  Before displaying the link list (after paging):  {loop=\"$plugin_start_zone\"}\n     {$value}\n{/loop}  For every links (icons):  {loop=\"$value.link_plugin\"}\n    <span>{$value}</span>\n{/loop}  Before end paging:  {loop=\"$plugin_end_zone\"}\n     {$value}\n{/loop}  linklist.paging.html  After the \"private only\" icon:  {loop=\"$action_plugin\"}\n     {$value}\n{/loop}  editlink.html  After tags field:  {loop=\"$edit_link_plugin\"}\n     {$value}\n{/loop}  tools.html  After the last tool:  {loop=\"$tools_plugin\"}\n     {$value}\n{/loop}  picwall.html  Top:  <div id=\"plugin_zone_start_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_start_zone\"}\n        {$value}\n    {/loop}\n</div>  Bottom:  <div id=\"plugin_zone_end_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_end_zone\"}\n        {$value}\n    {/loop}\n</div>  tagcloud.html  Top:     <div id=\"plugin_zone_start_tagcloud\" class=\"plugin_zone\">\n        {loop=\"$plugin_start_zone\"}\n            {$value}\n        {/loop}\n    </div>  Bottom:      <div id=\"plugin_zone_end_tagcloud\" class=\"plugin_zone\">\n        {loop=\"$plugin_end_zone\"}\n            {$value}\n        {/loop}\n    </div>  daily.html  Top:  <div id=\"plugin_zone_start_picwall\" class=\"plugin_zone\">\n     {loop=\"$plugin_start_zone\"}\n         {$value}\n     {/loop}\n</div>  After every link:  <div class=\"dailyEntryFooter\">\n     {loop=\"$link.link_plugin\"}\n          {$value}\n     {/loop}\n</div>  Bottom:  <div id=\"plugin_zone_end_picwall\" class=\"plugin_zone\">\n    {loop=\"$plugin_end_zone\"}\n        {$value}\n    {/loop}\n</div>  feed.atom.xml  and  feed.rss.xml :  In headers tags section:  {loop=\"$feed_plugins_header\"}\n  {$value}\n{/loop}  After each entry:  {loop=\"$value.feed_plugins\"}\n  {$value}\n{/loop}",
            "title": "List of placeholders"
        },
        {
            "location": "/Release-Shaarli/",
            "text": "See  \nGit - Maintaining a project - Tagging your \nreleases\n.\n\n\nPrerequisites\n\n\nThis guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n    - i.e., the email address identified by the GPG key is the same as the one in your \n~/.gitconfig\n \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n    - \norigin\n pointing to your GitHub fork\n    - \nupstream\n pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n    - push the signed tag\n    - create a new release\n- \nComposer\n needs to be installed\n- The \nvenv\n Python 3 module needs to be installed for HTML documentation generation.\n\n\nGitHub release draft and \nCHANGELOG.md\n\n\nSee http://keepachangelog.com/en/0.3.0/ for changelog formatting.\n\n\nGitHub release draft\n\n\nGitHub allows drafting the release note for the upcoming release, from the \nReleases\n page. This way, the release note can be drafted while contributions are merged to \nmaster\n.\n\n\nCHANGELOG.md\n\n\nThis file should contain the same information as the release note draft for the upcoming version.\n\n\nUpdate it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version\n\n\n$ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]\n\n\n\n\nIncrement the version code, updated docs, create and push a signed tag\n\n\nGenerate documentation\n\n\n$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the HTML documentation from Markdown\n$ make htmlpages\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0\n\n\n\n\nCreate and merge a Pull Request\n\n\nThis one is pretty straightforward ;-)\n\n\nBump Shaarli version to v0.x branch\n\n\n$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5\n\n\n\n\nCreate and push a signed tag\n\n\n# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream\n\n\n\n\nVerify a signed tag\n\n\nv0.5.0\n is the first GPG-signed tag pushed on the Community Shaarli.\n\n\nLet's have a look at its signature!\n\n\n$ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam <virtualtam@flibidi.net>\" [ultimate]\n\n\n\n\nPublish the GitHub release\n\n\nUpdate release badges\n\n\nUpdate \nREADME.md\n so version badges display and point to the newly released Shaarli version(s), in the \nmaster\n branch.\n\n\nCreate a GitHub release from a Git tag\n\n\nFrom the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!\n\n\nGenerate and upload all-in-one release archives\n\n\nUsers with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts\n\n\nTo ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries.\n\n\nFrom the \nv0.5\n branch:\n\n\n$ make release_archive\n\n\n\n\nThis will create the following archives:\n- \nshaarli-vX.Y.Z-full.tar\n\n- \nshaarli-vX.Y.Z-full.zip\n\n\nThe archives need to be manually uploaded on the previously created GitHub release.\n\n\nUpdate \nstable\n and \nlatest\n branches\n\n\n$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
            "title": "Release Shaarli"
        },
        {
            "location": "/Release-Shaarli/#prerequisites",
            "text": "This guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n    - i.e., the email address identified by the GPG key is the same as the one in your  ~/.gitconfig  \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n    -  origin  pointing to your GitHub fork\n    -  upstream  pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n    - push the signed tag\n    - create a new release\n-  Composer  needs to be installed\n- The  venv  Python 3 module needs to be installed for HTML documentation generation.",
            "title": "Prerequisites"
        },
        {
            "location": "/Release-Shaarli/#github-release-draft-and-changelogmd",
            "text": "See http://keepachangelog.com/en/0.3.0/ for changelog formatting.",
            "title": "GitHub release draft and CHANGELOG.md"
        },
        {
            "location": "/Release-Shaarli/#github-release-draft",
            "text": "GitHub allows drafting the release note for the upcoming release, from the  Releases  page. This way, the release note can be drafted while contributions are merged to  master .",
            "title": "GitHub release draft"
        },
        {
            "location": "/Release-Shaarli/#changelogmd",
            "text": "This file should contain the same information as the release note draft for the upcoming version.  Update it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version  $ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]",
            "title": "CHANGELOG.md"
        },
        {
            "location": "/Release-Shaarli/#increment-the-version-code-updated-docs-create-and-push-a-signed-tag",
            "text": "",
            "title": "Increment the version code, updated docs, create and push a signed tag"
        },
        {
            "location": "/Release-Shaarli/#generate-documentation",
            "text": "$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the HTML documentation from Markdown\n$ make htmlpages\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0",
            "title": "Generate documentation"
        },
        {
            "location": "/Release-Shaarli/#create-and-merge-a-pull-request",
            "text": "This one is pretty straightforward ;-)",
            "title": "Create and merge a Pull Request"
        },
        {
            "location": "/Release-Shaarli/#bump-shaarli-version-to-v0x-branch",
            "text": "$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5",
            "title": "Bump Shaarli version to v0.x branch"
        },
        {
            "location": "/Release-Shaarli/#create-and-push-a-signed-tag",
            "text": "# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream",
            "title": "Create and push a signed tag"
        },
        {
            "location": "/Release-Shaarli/#verify-a-signed-tag",
            "text": "v0.5.0  is the first GPG-signed tag pushed on the Community Shaarli.  Let's have a look at its signature!  $ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam <virtualtam@flibidi.net>\" [ultimate]",
            "title": "Verify a signed tag"
        },
        {
            "location": "/Release-Shaarli/#publish-the-github-release",
            "text": "",
            "title": "Publish the GitHub release"
        },
        {
            "location": "/Release-Shaarli/#update-release-badges",
            "text": "Update  README.md  so version badges display and point to the newly released Shaarli version(s), in the  master  branch.",
            "title": "Update release badges"
        },
        {
            "location": "/Release-Shaarli/#create-a-github-release-from-a-git-tag",
            "text": "From the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!",
            "title": "Create a GitHub release from a Git tag"
        },
        {
            "location": "/Release-Shaarli/#generate-and-upload-all-in-one-release-archives",
            "text": "Users with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts  To ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries.  From the  v0.5  branch:  $ make release_archive  This will create the following archives:\n-  shaarli-vX.Y.Z-full.tar \n-  shaarli-vX.Y.Z-full.zip  The archives need to be manually uploaded on the previously created GitHub release.",
            "title": "Generate and upload all-in-one release archives"
        },
        {
            "location": "/Release-Shaarli/#update-stable-and-latest-branches",
            "text": "$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
            "title": "Update stable and latest branches"
        },
        {
            "location": "/Versioning-and-Branches/",
            "text": "WORK IN PROGRESS\n\n\nIt's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.\n\n\nmaster\n branch\n\n\nThe \nmaster\n branch is the development branch. Any new change MUST go through this branch using Pull Requests.\n\n\nRemarks:\n\n\n\n\nThis branch shouldn't be used for production as it isn't necessary stable.\n\n\n3rd party aren't required to be compatible with the latest changes.\n\n\nOfficial plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.\n\n\nThe version in this branch is always \ndev\n.\n\n\n\n\nv0.x\n branch\n\n\nThis \nv0.x\n branch, points to the latest \nv0.x.y\n release.\n\n\nExplanation:\n\n\nWhen a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.\n\n\nIn this case, the issue is fixed in the \nmaster\n branch, and the fix is backported the to the \nv0.x\n branch. Then a new release is made from the \nv0.x\n branch.\n\n\nThis workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.\n\n\nlatest\n branch\n\n\nThis branch point the latest release. It recommended to use it to get the latest tested changes.\n\n\nstable\n branch\n\n\nThe \nstable\n branch doesn't contain any major bug, and is one major digit version behind the latest release.\n\n\nFor example, the current latest release is \nv0.8.3\n, the stable branch is an alias to the latest \nv0.7.x\n release. When the \nv0.9.0\n version will be released, the stable will move to the latest \nv0.8.x\n release.\n\n\nRemarks:\n\n\n\n\nShaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.\n\n\n\n\nReleases\n\n\nReleases are always made from the latest \nv0.x\n branch.\n\n\nNote that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.\n\n\nAdvices on 3rd party git repos workflow\n\n\nVersioning\n\n\nAny 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 \nchangelog\n (\nDraft\n means not released yet) and the commit log (like \ntpl\n folder\n for themes)). You can either:\n\n\n\n\nuse the Shaarli version number, with your repo version. For example, if Shaarli \nv0.8.3\n is released, publish a \nv0.8.3-1\n release, where \nv0.8.3\n states Shaarli compatibility and \n-1\n is your own version digit for the current Shaarli version.\n\n\nuse your own versioning scheme, and state Shaarli compatibility in the release description.\n\n\n\n\nUsing this, any user will be able to pick the release matching his own Shaarli version.\n\n\nMajor bugfix backport releases\n\n\nTo be able to support backported fixes, it recommended to use our workflow:\n\n\n# In master, fix the major bug\ngit commit -m \"Katastrophe\"\ngit push origin master\n# Get your commit hash\ngit log --format=\"%H\" -n 1\n# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)\ngit checkout -b katastrophe v0.8.2-1\n# Backport the fix commit to your brand new branch\ngit cherry-pick <fix commit hash>\ngit push origin katastrophe\n# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`",
            "title": "Versioning and Branches"
        },
        {
            "location": "/Versioning-and-Branches/#master-branch",
            "text": "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.  The version in this branch is always  dev .",
            "title": "master branch"
        },
        {
            "location": "/Versioning-and-Branches/#v0x-branch",
            "text": "This  v0.x  branch, points to the latest  v0.x.y  release.  Explanation:  When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.  In this case, the issue is fixed in the  master  branch, and the fix is backported the to the  v0.x  branch. Then a new release is made from the  v0.x  branch.  This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.",
            "title": "v0.x branch"
        },
        {
            "location": "/Versioning-and-Branches/#latest-branch",
            "text": "This branch point the latest release. It recommended to use it to get the latest tested changes.",
            "title": "latest branch"
        },
        {
            "location": "/Versioning-and-Branches/#stable-branch",
            "text": "The  stable  branch doesn't contain any major bug, and is one major digit version behind the latest release.  For example, the current latest release is  v0.8.3 , the stable branch is an alias to the latest  v0.7.x  release. When the  v0.9.0  version will be released, the stable will move to the latest  v0.8.x  release.  Remarks:   Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.",
            "title": "stable branch"
        },
        {
            "location": "/Versioning-and-Branches/#releases",
            "text": "Releases are always made from the latest  v0.x  branch.  Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.",
            "title": "Releases"
        },
        {
            "location": "/Versioning-and-Branches/#advices-on-3rd-party-git-repos-workflow",
            "text": "",
            "title": "Advices on 3rd party git repos workflow"
        },
        {
            "location": "/Versioning-and-Branches/#versioning",
            "text": "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  ( Draft  means not released yet) and the commit log (like  tpl  folder  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.",
            "title": "Versioning"
        },
        {
            "location": "/Versioning-and-Branches/#major-bugfix-backport-releases",
            "text": "To be able to support backported fixes, it recommended to use our workflow:  # In master, fix the major bug\ngit commit -m \"Katastrophe\"\ngit push origin master\n# Get your commit hash\ngit log --format=\"%H\" -n 1\n# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)\ngit checkout -b katastrophe v0.8.2-1\n# Backport the fix commit to your brand new branch\ngit cherry-pick <fix commit hash>\ngit push origin katastrophe\n# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`",
            "title": "Major bugfix backport releases"
        },
        {
            "location": "/Security/",
            "text": "Client browser\n\n\n\n\nShaarli relies on \nHTTP_REFERER\n for some functions (like redirects and clicking on tags). If you have disabled or masqueraded \nHTTP_REFERER\n in your browser, some features of Shaarli may not work\n\n\n\n\nPHP\n\n\n\n\nmagic_quotes\n is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with \nmagic_quotes\n on, so you should not be bothered even on crappy hosts.\n\n\n\n\nServer and sessions\n\n\n\n\nDirectories are protected using \n.htaccess\n files\n\n\nForms are protected against XSRF (Cross-site requests forgery):\n\n\nForms which act on data (save,delete\u2026) contain a token generated by the server.\n\n\nAny posted form which does not contain a valid token is rejected.\n\n\nAny token can only be used once.\n\n\nTokens are attached to the session and cannot be reused in another session.\n\n\nSessions automatically expire after 60 minutes.\n\n\nSessions are protected against hijacking: the session ID cannot be used from a different IP address.\n\n\n\n\nShaarli datastore and configuration\n\n\n\n\nThe password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.\n\n\nLinks are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a \n.php\n file.\n\n\nEven if the server does not support \n.htaccess\n files, the data file will still not be readable by URL.\n\n\nThe database looks like this:\n\n\n\n\n<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...\n...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>\n\n\n\n\n\n\nSmall hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. \n20110923_150523\n) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only \nA-Z a-z 0-9 - _\n and \n@\n.",
            "title": "Security"
        },
        {
            "location": "/Security/#client-browser",
            "text": "Shaarli relies on  HTTP_REFERER  for some functions (like redirects and clicking on tags). If you have disabled or masqueraded  HTTP_REFERER  in your browser, some features of Shaarli may not work",
            "title": "Client browser"
        },
        {
            "location": "/Security/#php",
            "text": "magic_quotes  is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with  magic_quotes  on, so you should not be bothered even on crappy hosts.",
            "title": "PHP"
        },
        {
            "location": "/Security/#server-and-sessions",
            "text": "Directories are protected using  .htaccess  files  Forms are protected against XSRF (Cross-site requests forgery):  Forms which act on data (save,delete\u2026) contain a token generated by the server.  Any posted form which does not contain a valid token is rejected.  Any token can only be used once.  Tokens are attached to the session and cannot be reused in another session.  Sessions automatically expire after 60 minutes.  Sessions are protected against hijacking: the session ID cannot be used from a different IP address.",
            "title": "Server and sessions"
        },
        {
            "location": "/Security/#shaarli-datastore-and-configuration",
            "text": "The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.  Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a  .php  file.  Even if the server does not support  .htaccess  files, the data file will still not be readable by URL.  The database looks like this:   <?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...\n...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>   Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg.  20110923_150523 ) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only  A-Z a-z 0-9 - _  and  @ .",
            "title": "Shaarli datastore and configuration"
        },
        {
            "location": "/Static-analysis/",
            "text": "WIP\n\n\nThis topic is currently being discussed here:\n- \nFix coding style (static analysis)\n (#95)\n- \nContinuous Integration tools & features\n (#130)\n\n\nUsage\n\n\nStatic analysis tools can be installed with Composer, and used through Shaarli's \nMakefile\n.\n\n\nFor an overview of the available features, see:\n- \nCode quality: Makefile to run static code checkers\n (#124)\n- \nRun PHPCS against different coding standards\n (#276)",
            "title": "Static analysis"
        },
        {
            "location": "/Static-analysis/#wip",
            "text": "This topic is currently being discussed here:\n-  Fix coding style (static analysis)  (#95)\n-  Continuous Integration tools & features  (#130)",
            "title": "WIP"
        },
        {
            "location": "/Static-analysis/#usage",
            "text": "Static analysis tools can be installed with Composer, and used through Shaarli's  Makefile .  For an overview of the available features, see:\n-  Code quality: Makefile to run static code checkers  (#124)\n-  Run PHPCS against different coding standards  (#276)",
            "title": "Usage"
        },
        {
            "location": "/Theming/",
            "text": "Foreword\n\n\nThere are two ways of customizing how Shaarli looks:\n\n\n\n\nby using a custom CSS to override Shaarli's CSS\n\n\nby using a full theme that provides its own RainTPL templates, CSS and Javascript resources\n\n\n\n\nCustom CSS\n\n\nShaarli's appearance can be modified by adding CSS rules to:\n- Shaarli < \nv0.9.0\n: \ninc/user.css\n\n- Shaarli >= \nv0.9.0\n: \ndata/user.css\n\n\nThis file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.\n\n\nNote\n: Do not edit \ntpl/default/css/shaarli.css\n! Your changes would be overridden when updating Shaarli.\n\n\nSee also \nDownload CSS styles from an OPML list\n\n\nThemes\n\n\nWARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.\n\n\nInstallation:\n- find a theme you'd like to install\n- copy or clone the theme folder under \ntpl/<a_sweet_theme>\n\n- enable the theme:\n    - Shaarli < \nv0.9.0\n: edit \ndata/config.json.php\n and set the value of \nraintpl_tpl\n to the new theme name:\n      \n\"raintpl_tpl\": \"tpl\\/my-template\\/\"\n\n    - Shaarli >= \nv0.9.0\n: select the theme through the \nTools\n page\n\n\nCommunity CSS & themes\n\n\nCustom CSS\n\n\n\n\nmrjovanovic/serious-theme-shaarli\n - A serious theme for Shaarli\n\n\nshaarli/shaarli-themes\n\n\n\n\nThemes\n\n\n\n\nAkibaTech/Shaarli Superhero Theme\n - A template/theme for Shaarli\n\n\nalexisju/albinomouse-template\n - A full template for Shaarli\n\n\nArthurHoaro/shaarli-launch\n - Customizable Shaarli theme\n\n\ndhoko/ShaarliTemplate\n - A template/theme for Shaarli\n\n\nkalvn/shaarli-blocks\n - A template/theme for Shaarli\n\n\nkalvn/Shaarli-Material\n - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone\n\n\nManufacturaInd/shaarli-2004licious-theme\n - A template/theme as a humble homage to the early looks of the del.icio.us site\n\n\n\n\nShaarli forks\n\n\n\n\nmisterair/Limonade\n - A fork of (legacy) Shaarli with a new template\n\n\nvivienhaese/shaarlitheme\n - A Shaarli fork meant to be run in an openshift instance\n\n\n\n\nExample installation: AlbinoMouse theme\n\n\nWith the following configuration:\n- Apache 2 / PHP 5.6\n- user sites are enabled, e.g. \n/home/user/public_html/somedir\n is served as \nhttp://localhost/~user/somedir\n\n- \nhttp\n is the name of the Apache user\n\n\n$ cd ~/public_html\n\n# clone repositories\n$ git clone https://github.com/shaarli/Shaarli.git shaarli\n$ pushd shaarli/tpl\n$ git clone https://github.com/alexisju/albinomouse-template.git\n$ popd\n\n# set access rights for Apache\n$ chgrp -R http shaarli\n$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp\n\n\n\n\nGet config written:\n- go to the freshly installed site\n- fill the install form\n- log in to Shaarli\n\n\nEdit Shaarli's \nconfiguration|Shaarli configuration\n:\n\n\n# the file should be owned by Apache, thus not writeable => sudo\n$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php",
            "title": "Theming"
        },
        {
            "location": "/Theming/#foreword",
            "text": "There are two ways of customizing how Shaarli looks:   by using a custom CSS to override Shaarli's CSS  by using a full theme that provides its own RainTPL templates, CSS and Javascript resources",
            "title": "Foreword"
        },
        {
            "location": "/Theming/#custom-css",
            "text": "Shaarli's appearance can be modified by adding CSS rules to:\n- Shaarli <  v0.9.0 :  inc/user.css \n- 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.  See also  Download CSS styles from an OPML list",
            "title": "Custom CSS"
        },
        {
            "location": "/Theming/#themes",
            "text": "WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.  Installation:\n- find a theme you'd like to install\n- copy or clone the theme folder under  tpl/<a_sweet_theme> \n- enable the theme:\n    - Shaarli <  v0.9.0 : edit  data/config.json.php  and set the value of  raintpl_tpl  to the new theme name:\n       \"raintpl_tpl\": \"tpl\\/my-template\\/\" \n    - Shaarli >=  v0.9.0 : select the theme through the  Tools  page",
            "title": "Themes"
        },
        {
            "location": "/Theming/#community-css-themes",
            "text": "",
            "title": "Community CSS &amp; themes"
        },
        {
            "location": "/Theming/#custom-css_1",
            "text": "mrjovanovic/serious-theme-shaarli  - A serious theme for Shaarli  shaarli/shaarli-themes",
            "title": "Custom CSS"
        },
        {
            "location": "/Theming/#themes_1",
            "text": "AkibaTech/Shaarli Superhero Theme  - A template/theme for Shaarli  alexisju/albinomouse-template  - A full template for Shaarli  ArthurHoaro/shaarli-launch  - Customizable Shaarli theme  dhoko/ShaarliTemplate  - A template/theme for Shaarli  kalvn/shaarli-blocks  - A template/theme for Shaarli  kalvn/Shaarli-Material  - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone  ManufacturaInd/shaarli-2004licious-theme  - A template/theme as a humble homage to the early looks of the del.icio.us site",
            "title": "Themes"
        },
        {
            "location": "/Theming/#shaarli-forks",
            "text": "misterair/Limonade  - A fork of (legacy) Shaarli with a new template  vivienhaese/shaarlitheme  - A Shaarli fork meant to be run in an openshift instance",
            "title": "Shaarli forks"
        },
        {
            "location": "/Theming/#example-installation-albinomouse-theme",
            "text": "With the following configuration:\n- Apache 2 / PHP 5.6\n- user sites are enabled, e.g.  /home/user/public_html/somedir  is served as  http://localhost/~user/somedir \n-  http  is the name of the Apache user  $ cd ~/public_html\n\n# clone repositories\n$ git clone https://github.com/shaarli/Shaarli.git shaarli\n$ pushd shaarli/tpl\n$ git clone https://github.com/alexisju/albinomouse-template.git\n$ popd\n\n# set access rights for Apache\n$ chgrp -R http shaarli\n$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp  Get config written:\n- go to the freshly installed site\n- fill the install form\n- log in to Shaarli  Edit Shaarli's  configuration|Shaarli configuration :  # the file should be owned by Apache, thus not writeable => sudo\n$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php",
            "title": "Example installation: AlbinoMouse theme"
        },
        {
            "location": "/Unit-tests/",
            "text": "Setup your environment for tests\n\n\nThe framework used is \nPHPUnit\n; it can be installed with \nComposer\n, which is a dependency management tool.\n\n\nRegarding Composer, you can either use:\n\n a system-wide version, e.g. installed through your distro's package manager\n\n a local version, downloadable \nhere\n\n\nSample usage\n\n\n# system-wide version\n$ composer install\n$ composer update\n\n# local version\n$ php composer.phar self-update\n$ php composer.phar install\n$ php composer.phar update\n\n\n\n\nInstall Shaarli dev dependencies\n\n\n$ cd /path/to/shaarli\n$ composer update\n\n\n\n\nInstall and enable Xdebug to generate PHPUnit coverage reports\n\n\nFor Debian-based distros:\n\n\n$ aptitude install php5-xdebug\n\n\n\n\nFor ArchLinux:\n\n\n$ pacman -S xdebug\n\n\n\n\nThen add the following line to \n/etc/php/php.ini\n:\n\n\nzend_extension=xdebug.so\n\n\n\n\nRun unit tests\n\n\nSuccessful test suite:\n\n\n$ make test\n\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\n....................................\n\nTime: 759 ms, Memory: 8.25Mb\n\nOK (36 tests, 65 assertions)\n\n\n\n\nTest suite with failures and errors:\n\n\n$ make test\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\nE..FF...............................\n\nTime: 802 ms, Memory: 8.25Mb\n\nThere was 1 error:\n\n1) LinkDBTest::testConstructLoggedIn\nMissing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\\\nDBTest.php on line 79 and defined\n\n/home/virtualtam/public_html/shaarli/application/LinkDB.php:58\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79\n\n--\n\nThere were 2 failures:\n\n1) LinkDBTest::testCheckDBNew\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121\n\n2) LinkDBTest::testCheckDBLoad\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133\n\nFAILURES!\nTests: 36, Assertions: 63, Errors: 1, Failures: 2.\n\n\n\n\nTest results and coverage\n\n\nBy default, PHPUnit will run all suitable tests found under the \ntests\n directory.\n\n\nEach test has 3 possible outcomes:\n\n \n.\n - success\n\n \nF\n - failure: the test was run but its results are invalid\n * the code does not behave as expected\n * dependencies to external elements: globals, session, cache...\n* \nE\n - error: something went wrong and the tested code has crashed\n * typos in the code, or in the test code\n * dependencies to missing external elements\n\n\nIf Xdebug has been installed and activated, two coverage reports will be generated:\n\n a summary in the console\n\n a detailed HTML report with metrics for tested code\n * to open it in a web browser: \nfirefox coverage/index.html &\n\n\nExecuting specific tests\n\n\nAdd a \n@group\n annotation in a test class or method comment:\n\n\n/**\n * Netscape bookmark import\n * @group WIP\n */\nclass BookmarkImportTest extends PHPUnit_Framework_TestCase\n{\n   [...]\n}\n\n\n\n\nTo run all tests annotated with \n@group WIP\n:\n\n\n$ vendor/bin/phpunit --group WIP tests/",
            "title": "Unit tests"
        },
        {
            "location": "/Unit-tests/#setup-your-environment-for-tests",
            "text": "The framework used is  PHPUnit ; it can be installed with  Composer , which is a dependency management tool.  Regarding Composer, you can either use:  a system-wide version, e.g. installed through your distro's package manager  a local version, downloadable  here",
            "title": "Setup your environment for tests"
        },
        {
            "location": "/Unit-tests/#sample-usage",
            "text": "# system-wide version\n$ composer install\n$ composer update\n\n# local version\n$ php composer.phar self-update\n$ php composer.phar install\n$ php composer.phar update",
            "title": "Sample usage"
        },
        {
            "location": "/Unit-tests/#install-shaarli-dev-dependencies",
            "text": "$ cd /path/to/shaarli\n$ composer update",
            "title": "Install Shaarli dev dependencies"
        },
        {
            "location": "/Unit-tests/#install-and-enable-xdebug-to-generate-phpunit-coverage-reports",
            "text": "For Debian-based distros:  $ aptitude install php5-xdebug  For ArchLinux:  $ pacman -S xdebug  Then add the following line to  /etc/php/php.ini :  zend_extension=xdebug.so",
            "title": "Install and enable Xdebug to generate PHPUnit coverage reports"
        },
        {
            "location": "/Unit-tests/#run-unit-tests",
            "text": "Successful test suite:  $ make test\n\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\n....................................\n\nTime: 759 ms, Memory: 8.25Mb\n\nOK (36 tests, 65 assertions)  Test suite with failures and errors:  $ make test\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\nE..FF...............................\n\nTime: 802 ms, Memory: 8.25Mb\n\nThere was 1 error:\n\n1) LinkDBTest::testConstructLoggedIn\nMissing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\\\nDBTest.php on line 79 and defined\n\n/home/virtualtam/public_html/shaarli/application/LinkDB.php:58\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79\n\n--\n\nThere were 2 failures:\n\n1) LinkDBTest::testCheckDBNew\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121\n\n2) LinkDBTest::testCheckDBLoad\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133\n\nFAILURES!\nTests: 36, Assertions: 63, Errors: 1, Failures: 2.",
            "title": "Run unit tests"
        },
        {
            "location": "/Unit-tests/#test-results-and-coverage",
            "text": "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\n * the code does not behave as expected\n * dependencies to external elements: globals, session, cache...\n*  E  - error: something went wrong and the tested code has crashed\n * typos in the code, or in the test code\n * 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\n * to open it in a web browser:  firefox coverage/index.html &",
            "title": "Test results and coverage"
        },
        {
            "location": "/Unit-tests/#executing-specific-tests",
            "text": "Add a  @group  annotation in a test class or method comment:  /**\n * Netscape bookmark import\n * @group WIP\n */\nclass BookmarkImportTest extends PHPUnit_Framework_TestCase\n{\n   [...]\n}  To run all tests annotated with  @group WIP :  $ vendor/bin/phpunit --group WIP tests/",
            "title": "Executing specific tests"
        },
        {
            "location": "/FAQ/",
            "text": "Why did you create Shaarli ?\n\n\nI was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And\u2026 oh\u2026 \ntheir Firefox addon sends to Diigo every single URL you visit\n (Don't believe me ? Use \nTamper Data\n and open any page).\n\n\nEnough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.\n\n\nWhy use Shaarli and not Delicious/Diigo ?\n\n\nWith Shaarli:\n\n\n\n\nThe data is yours: It's hosted on your server.\n\n\nNever fear of having your data locked-in.\n\n\nNever fear to have your data sold to third party.\n\n\nYour private links are not hosted on a third party server.\n\n\nYou are not tracked by browser addons (like Diigo does)\n\n\nYou can change the look and feel of the pages if you want.\n\n\nYou can change the behaviour of the program.\n\n\nIt's magnitude faster than most bookmarking services.\n\n\n\n\nWhat does Shaarli mean?\n\n\nShaarli is for shaaring your links.\n\n\nMy Shaarli is broken!\n\n\nFirst of all, ensure that both the \nweb server\n and \nShaarli\n are correctly configured, and that your installation is \nsupported\n.\n\n\nIf everything looks right but the issue(s) remain(s), please:\n- take a look at the \ntroubleshooting\n section\n- come \nchat with us\n on Gitter, we'll be happy to help ;-)\n- browse active \nissues\n and \nPull Requests\n\n    - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)\n    - else, \nopen a new issue\n, and provide information about the problem:\n        - \nwhat happens?\n - display glitches, invalid data, security flaws...\n        - \nwhat is your configuration?\n  - OS, server version, activated extensions, web browser...\n        - \nis it reproducible?\n\n\nWhy not use a real database? Files are slow!\n\n\nDoes browsing \nthis page\n feel slow? Try browsing older pages, too.\n\n\nIt's not slow at all, is it? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why?\n\n\nThe data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.",
            "title": "FAQ"
        },
        {
            "location": "/FAQ/#why-did-you-create-shaarli",
            "text": "I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And\u2026 oh\u2026  their Firefox addon sends to Diigo every single URL you visit  (Don't believe me ? Use  Tamper Data  and open any page).  Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.",
            "title": "Why did you create Shaarli ?"
        },
        {
            "location": "/FAQ/#why-use-shaarli-and-not-deliciousdiigo",
            "text": "With Shaarli:   The data is yours: It's hosted on your server.  Never fear of having your data locked-in.  Never fear to have your data sold to third party.  Your private links are not hosted on a third party server.  You are not tracked by browser addons (like Diigo does)  You can change the look and feel of the pages if you want.  You can change the behaviour of the program.  It's magnitude faster than most bookmarking services.",
            "title": "Why use Shaarli and not Delicious/Diigo ?"
        },
        {
            "location": "/FAQ/#what-does-shaarli-mean",
            "text": "Shaarli is for shaaring your links.",
            "title": "What does Shaarli mean?"
        },
        {
            "location": "/FAQ/#my-shaarli-is-broken",
            "text": "First of all, ensure that both the  web server  and  Shaarli  are correctly configured, and that your installation is  supported .  If everything looks right but the issue(s) remain(s), please:\n- take a look at the  troubleshooting  section\n- come  chat with us  on Gitter, we'll be happy to help ;-)\n- browse active  issues  and  Pull Requests \n    - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)\n    - else,  open a new issue , and provide information about the problem:\n        -  what happens?  - display glitches, invalid data, security flaws...\n        -  what is your configuration?   - OS, server version, activated extensions, web browser...\n        -  is it reproducible?",
            "title": "My Shaarli is broken!"
        },
        {
            "location": "/FAQ/#why-not-use-a-real-database-files-are-slow",
            "text": "Does browsing  this page  feel slow? Try browsing older pages, too.  It's not slow at all, is it? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why?  The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.",
            "title": "Why not use a real database? Files are slow!"
        },
        {
            "location": "/Community-&-Related-software/",
            "text": "Unofficial but related work on Shaarli. If you maintain one of these, please get in touch with us to help us find a way to adapt your work to our fork.\n\n\nTODO: contact repos owners to see if they'd like to standardize their work with the community fork.\n\n\nCommunity\n\n\n\n\nLiens en vrac de sebsauvage\n - the original Shaarli\n\n\nA large list of Shaarlis\n\n\nA list of working Shaarli aggregators\n\n\nA list of some known Shaarlis\n\n\nAdieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net\n (fr) \n16/09/2011 - the original post about Shaarli\n\n\nOriginal ideas/fixme/TODO page\n\n\nOriginal discussion page\n (fr)\n\n\nOriginal revisions history\n\n\nShaarli.fr/my\n - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of \nDMeloni\n\n\n\n\nArticles and social media discussions\n\n\n\n\n2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176\n\n\n2015-08-15 - Reddit - \nQuestion about migrating from WordPress to Shaarli.\n\n\n2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366\n\n\n2015-05-12 - Reddit - \nshaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)\n\n\n\n\nThird party plugins\n\n\n\n\nautosave\n by \n@kalvn\n: Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.\n\n\nCode Coloration\n by \n@ArthurHoaro\n: client side code syntax highlighter.\n\n\nDisqus\n by \n@kalvn\n: Adds Disqus comment system to your Shaarli.\n\n\nemojione\n by \n@NerosTie\n: Add colorful emojis to your Shaarli.\n\n\ngoogle analytics\n by \n@ericjuden\n: Adds Google Analytics tracking support\n\n\nlaunch\n - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.\n\n\nrelated\n by \n@ilesinge\n - Show related links based on the number of identical tags.\n\n\nsocial\n by \n@alexisju\n: share links to social networks.\n\n\nshaarli2twitter\n by \n@ArthurHoaro\n - Automatically tweet your shared links from Shaarli\n\n\n\n\nThemes\n\n\nSee \nTheming\n for the list of community-contributed themes, and an installation guide.\n\n\nServer apps\n\n\n\n\nshaarchiver\n - Archive your Shaarli bookmarks and their content\n\n\nshaarli-river\n - An aggregator for shaarlis with many features \n\n\nShaarlo\n - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: \nshaarli.fr\n)\n\n\nShaarlimages\n - An image-oriented aggregator for Shaarlis\n\n\nmknexen/shaarli-api\n - A REST API for Shaarli\n\n\nSelf dead link\n - Detect dead links on shaarli. This version use the database of shaarli. \nAnother version\n, can be used for other shaarli instances (but is more resource consuming).\n\n\nBookmark Archiver\n - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html. \n\n\n\n\nMobile Apps\n\n\n\n\nShaarliOS\n iOS share extension - see \n#308\n for some promo codes,\n\n\nShaarli for Android\n - Android application that adds Shaarli as a sharing provider\n\n\nShaarlier for Android\n - Android application to simply add links directly into your Shaarli\n\n\n\n\nIntegration with other platforms\n\n\n\n\ntt-rss-shaarli\n - \nTiny-Tiny RSS\n plugin that adds support for sharing articles with Shaarli\n\n\noctopress-shaarli\n - Octopress plugin to retrieve Shaarli links on the sidebar\n\n\nScuttle to Shaarli\n - Import bookmarks from Scuttle\n\n\n\n\nAlternatives to Shaarli\n\n\nSee the \nbookmarks & link sharing\n section on \nawesome-selfhosted\n.",
            "title": "Community & Related software"
        },
        {
            "location": "/Community-&-Related-software/#community",
            "text": "Liens en vrac de sebsauvage  - the original Shaarli  A large list of Shaarlis  A list of working Shaarli aggregators  A list of some known Shaarlis  Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net  (fr)  16/09/2011 - the original post about Shaarli  Original ideas/fixme/TODO page  Original discussion page  (fr)  Original revisions history  Shaarli.fr/my  - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of  DMeloni",
            "title": "Community"
        },
        {
            "location": "/Community-&-Related-software/#articles-and-social-media-discussions",
            "text": "2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176  2015-08-15 - Reddit -  Question about migrating from WordPress to Shaarli.  2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366  2015-05-12 - Reddit -  shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)",
            "title": "Articles and social media discussions"
        },
        {
            "location": "/Community-&-Related-software/#third-party-plugins",
            "text": "autosave  by  @kalvn : Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.  Code Coloration  by  @ArthurHoaro : client side code syntax highlighter.  Disqus  by  @kalvn : Adds Disqus comment system to your Shaarli.  emojione  by  @NerosTie : Add colorful emojis to your Shaarli.  google analytics  by  @ericjuden : Adds Google Analytics tracking support  launch  - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.  related  by  @ilesinge  - Show related links based on the number of identical tags.  social  by  @alexisju : share links to social networks.  shaarli2twitter  by  @ArthurHoaro  - Automatically tweet your shared links from Shaarli",
            "title": "Third party plugins"
        },
        {
            "location": "/Community-&-Related-software/#themes",
            "text": "See  Theming  for the list of community-contributed themes, and an installation guide.",
            "title": "Themes"
        },
        {
            "location": "/Community-&-Related-software/#server-apps",
            "text": "shaarchiver  - Archive your Shaarli bookmarks and their content  shaarli-river  - An aggregator for shaarlis with many features   Shaarlo  - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers:  shaarli.fr )  Shaarlimages  - An image-oriented aggregator for Shaarlis  mknexen/shaarli-api  - A REST API for Shaarli  Self dead link  - Detect dead links on shaarli. This version use the database of shaarli.  Another version , can be used for other shaarli instances (but is more resource consuming).  Bookmark Archiver  - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.",
            "title": "Server apps"
        },
        {
            "location": "/Community-&-Related-software/#mobile-apps",
            "text": "ShaarliOS  iOS share extension - see  #308  for some promo codes,  Shaarli for Android  - Android application that adds Shaarli as a sharing provider  Shaarlier for Android  - Android application to simply add links directly into your Shaarli",
            "title": "Mobile Apps"
        },
        {
            "location": "/Community-&-Related-software/#integration-with-other-platforms",
            "text": "tt-rss-shaarli  -  Tiny-Tiny RSS  plugin that adds support for sharing articles with Shaarli  octopress-shaarli  - Octopress plugin to retrieve Shaarli links on the sidebar  Scuttle to Shaarli  - Import bookmarks from Scuttle",
            "title": "Integration with other platforms"
        },
        {
            "location": "/Community-&-Related-software/#alternatives-to-shaarli",
            "text": "See the  bookmarks & link sharing  section on  awesome-selfhosted .",
            "title": "Alternatives to Shaarli"
        }
    ]
}