nextcloud · juliusknorr · Jun 9, 2023 · Apr 14, 2023 · Apr 18, 2023
diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst
@@ -4,8 +4,8 @@ Table of contents
 
 .. toctree::
     :maxdepth: 2
-     
-    index 
+
+    index
     release_notes
     release_schedule
     installation/index
@@ -16,6 +16,7 @@ Table of contents
     file_workflows/index
     groupware/index
     office/index
+    reference/index
     configuration_database/index
     configuration_mimetypes/index
     maintenance/index

diff --git a/admin_manual/office/index.rst b/admin_manual/office/index.rst
@@ -22,4 +22,4 @@ We are able to provide a solution for Online Office for the entire Nextcloud com
     installation
     configuration
     migration
-    troubleshooting
+    troubleshooting
diff --git a/admin_manual/reference/index.rst b/admin_manual/reference/index.rst
@@ -0,0 +1,26 @@
+====================
+Reference management
+====================
+
+The reference management system brings 2 features in Nextcloud:
+
+* :doc:`The link previews <./link_previews>` (also called reference widgets)
+* :doc:`The Smart Picker <./smart_picker>`
+
+Both those features are generic and need to be extended by the Nextcloud apps.
+
+Apps can add support for some HTTP links so previews are rendered in various places like Text documents and Talk messages.
+
+The Smart Picker is a frontend component which allows users to search or generate links or text.
+
+Apps can register Smart Picker providers to extend its capabilities.
+Administrators can choose which Smart Picker providers they want to
+make available to the users by choosing which apps they install.
+All the Smart Picker providers shipped in the recommended apps do **not** send any data to 3rd party services.
+Some community apps Smart Picker providers might rely on 3rd party services.
+
+.. toctree::
+    :maxdepth: 2
+
+    link_previews
+    smart_picker
diff --git a/admin_manual/reference/link_previews.rst b/admin_manual/reference/link_previews.rst
@@ -0,0 +1,56 @@
+=============
+Link previews
+=============
+
+Link previews are available in some places in Nextcloud.
+There are 3 types of link preview:
+
+* The ones for links that are supported by a reference provider
+    * Without custom reference widget (uses a default generic style, image + title + description)
+    * With custom reference widget (implemented by the app which supports the link)
+* Default ones from OpenGraph information. This is the fallback for every unsupported link
+
+Where do they appear?
+---------------------
+
+The link previews provided by the Nextcloud reference system appear in the following places:
+
+* Text (and Collectives pages, Notes, Deck card comments, Files comments etc...)
+    * Directly in the document content, next to the links
+    * Only one link preview per paragraph is rendered
+    * Custom widgets can be rendered
+* Talk
+    * In the messages
+    * Only one link preview per message is rendered
+    * Custom widgets can be rendered
+* Nextcloud Office
+    * In the document content when hovering on links
+    * Custom widgets are not rendered
+
+How does it work?
+-----------------
+
+The Nextcloud frontend asks the server to resolve the links via an API request. A rich object is returned as a response
+and is used by the frontend to render the preview.
+
+The apps can optionally register a custom reference widget to render a specific rich object type (on the links it supports).
+Therefore the apps have complete freedom over how some previews look like.
+
+Known link preview providers
+----------------------------
+
+* `Collectives <https://github.com/nextcloud/collectives>`_: Links to Collective pages
+* `Tables <https://github.com/nextcloud/tables>`_: Links to tables
+* `Deck <https://github.com/nextcloud/deck>`_: Links to boards, cards and comments
+* `Talk <https://github.com/nextcloud/spreed>`_: Links to conversations
+
+* `GitHub integration <https://github.com/nextcloud/integration_github>`_: Links to GitHub issues, pull requests, comments and repositories
+* `GitLab integration <https://github.com/nextcloud/integration_gitlab>`_: Links to Gitlab issues, merge requests, comments and repositories
+* `Zammad integration <https://github.com/nextcloud/integration_zammad>`_: Links to Zammad tickets
+* `Reddit integration <https://github.com/nextcloud/integration_reddit>`_: Links to subreddits, publications and comments
+* `Mastodon integration <https://github.com/nextcloud/integration_mastodon>`_: Links to members and toots
+* `The Movie Database integration <https://github.com/julien-nc/integration_tmdb>`_: Links to people, movies and series
+* `OpenStreetMap integration <https://github.com/julien-nc/integration_openstreetmap>`_: Location links from OpenStreetMap, Google maps, Bing maps, Here maps and Duckduckgo maps
+* `Giphy integration <https://github.com/julien-nc/integration_giphy>`_: Links to GIFs
+* `Notion integration <https://github.com/nextcloud/integration_notion>`_: Links to Notion documents
+* `Peertube integration <https://github.com/julien-nc/integration_peertube>`_: Links to videos
diff --git a/admin_manual/reference/smart_picker.rst b/admin_manual/reference/smart_picker.rst
@@ -0,0 +1,39 @@
+================
+The Smart Picker
+================
+
+Every Smart Picker provider can be enabled by installing and configuring the corresponding app.
+
+Where can it be used?
+---------------------
+
+The Smart Picker can be used in:
+
+* Text (and everywhere Text is used like Collectives pages, Deck card comments, Files comments...): by pressing the "/" key or using a top menu entry
+* Talk: by pressing the "/" key in the message composition input
+* Nextcloud Office: with a top menu entry
+* Mail: in the email composition area with a context menu entry
+
+Known Smart Picker providers
+----------------------------
+
+* Accessing internal data
+    * `Collectives <https://github.com/nextcloud/collectives>`_: To get links to Collective pages
+    * `Tables <https://github.com/nextcloud/tables>`_: To get links to tables
+    * `Deck <https://github.com/nextcloud/deck>`_: To get links to boards and comments
+    * `Talk <https://github.com/nextcloud/spreed>`_: To get links to conversations
+    * `Files <https://github.com/nextcloud/server>`_: To get internal links to files (not share links yet)
+    * `Text templates <https://github.com/julien-nc/text_templates>`_: To get personal and global text templates
+* Relying on 3rd party services
+    * `GitHub integration <https://github.com/nextcloud/integration_github>`_: To get links to GitHub issues, pull requests, and repositories
+    * `GitLab integration <https://github.com/nextcloud/integration_gitlab>`_: To get links to Gitlab issues, merge requests, and repositories
+    * `Zammad integration <https://github.com/nextcloud/integration_zammad>`_: To get links to Zammad tickets
+    * `Reddit integration <https://github.com/nextcloud/integration_reddit>`_: To get links to subreddits and publications
+    * `Mastodon integration <https://github.com/nextcloud/integration_mastodon>`_: To get links to members, toots and hashtags
+    * `The Movie Database integration <https://github.com/julien-nc/integration_tmdb>`_: To get links to people, movies and series
+    * `OpenStreetMap integration <https://github.com/julien-nc/integration_openstreetmap>`_: To get location links from OpenStreetMap
+    * `Giphy integration <https://github.com/julien-nc/integration_giphy>`_: To get links to GIFs
+    * `Notion integration <https://github.com/nextcloud/integration_notion>`_: To get links to Notion documents
+    * `Peertube integration <https://github.com/julien-nc/integration_peertube>`_: To get links to videos
+    * `OpenAI integration <https://github.com/julien-nc/integration_openai>`_: To generate images with Dall-e, text with GPT and transcribe/translate with Whisper (speech-to-text)
+    * `Replicate integration <https://github.com/julien-nc/integration_replicate>`_: To generate images with stable diffusion, and transcribe/translate with Whisper (speech-to-text)