docs: rewrite metadata page

docs/cli/metadata.rst

@@ -12,13 +12,18 @@ Streamlink supports a number of metadata variables that can be used in the follo
 - :option:`--record-and-pipe`
 
 Metadata variables are surrounded by curly braces and can be escaped by doubling the curly brace characters,
-eg. ``{variable}`` and ``{{not-a-variable}}``.
+e.g. ``{variable}`` and ``{{not-a-variable}}``.
 
-The availability of each variable depends on the used plugin and whether that plugin supports this kind of metadata.
-If a variable is unsupported or not available, then its substitution will either be a short placeholder text (:option:`--title`)
-or an empty string (:option:`--output`, :option:`--record`, :option:`--record-and-pipe`).
+.. warning::
 
-The :option:`--json` argument always lists the standard plugin metadata: ``id``, ``author``, ``category`` and ``title``.
+    The availability of each variable depends on the used plugin and whether that plugin supports this kind of metadata
+    (:ref:`check the metadata availability of each plugin here <plugins:Plugins>`). Be aware that depending on the stream,
+    certain metadata might not be available (yet), despite the plugin's implementation.
+
+    If no metadata is available for a specific variable, then its substitution will either be a short placeholder text
+    (:option:`--title`) or an empty string (:option:`--output`, :option:`--record`, :option:`--record-and-pipe`).
+
+**Conditional variables**
 
 .. list-table::
     :header-rows: 1
@@ -27,17 +32,26 @@ The :option:`--json` argument always lists the standard plugin metadata: ``id``,
     * - Variable
       - Description
     * - ``id``
-      - The unique ID of the stream, eg. an internal numeric ID or randomized string.
-    * - ``plugin``
-      - The plugin name. See :ref:`Plugins <plugins:Plugins>` for the name of each built-in plugin.
-    * - ``title``
-      - The stream's title, usually a short descriptive text.
+      - The unique ID of the stream, e.g. an internal numeric ID or randomized string.
     * - ``author``
-      - The stream's author, eg. a channel or broadcaster name.
+      - The stream's author, e.g. a channel or broadcaster name.
     * - ``category``
-      - The stream's category, eg. the name of a game being played, a music genre, etc.
+      - The stream's category, e.g. the name of a game being played, a music genre, etc.
     * - ``game``
       - Alias for ``category``.
+    * - ``title``
+      - The stream's title, usually a short descriptive text.
+
+**Generic variables**
+
+.. list-table::
+    :header-rows: 1
+    :class: table-custom-layout table-custom-layout-platform-locations
+
+    * - Variable
+      - Description
+    * - ``plugin``
+      - The name of the resolved plugin. See :ref:`Plugins <plugins:Plugins>` for the name of each built-in plugin.
     * - ``url``
       - The resolved URL of the stream.
     * - ``time``
@@ -48,6 +62,7 @@ The :option:`--json` argument always lists the standard plugin metadata: ``id``,
 
         The default format is ``%Y-%m-%d_%H-%M-%S``.
 
+.. _datetime.strftime(): https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
 
 Examples
 --------
@@ -57,4 +72,23 @@ Examples
     $ streamlink --title "{author} - {category} - {title}" <URL> [STREAM]
     $ streamlink --output "~/recordings/{author}/{category}/{id}-{time:%Y%m%d%H%M%S}.ts" <URL> [STREAM]
 
-.. _datetime.strftime(): https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
+The :option:`--json` argument always lists the conditional metadata.
+
+.. code-block:: console
+
+    $ streamlink --json twitch.tv/bobross | jq .metadata
+
+.. code-block:: json
+
+    {
+      "id": "49163597677",
+      "author": "BobRoss",
+      "category": "Art",
+      "title": "A Happy Little Weekend Marathon!"
+    }
+
+.. note::
+
+    Streamlink is not designed as a tool for general-purpose metadata retrieval. If your goal is to extract metadata from
+    specific streaming sites, then it's usually a better idea to implement this metadata retrieval yourself using
+    the available APIs of those sites or other means.