From ac391410216af98f7b4e60780f7cdae2dd36096d Mon Sep 17 00:00:00 2001
From: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
Date: Tue, 1 Apr 2025 14:00:30 -0400
Subject: [PATCH] Docs: dashboard list visualization refactor (#103211)

* Added configuration options heading and bumped other heading levels

* Moved dashboard list options into table

* Further restructured dashboard list options and made wording edits

* Added semantic line breaks

* Replaced screenshot with high res image

* Wording edits
---
 .../visualizations/dashboard-list/index.md    | 79 ++++++++-----------
 1 file changed, 35 insertions(+), 44 deletions(-)

diff --git a/docs/sources/panels-visualizations/visualizations/dashboard-list/index.md b/docs/sources/panels-visualizations/visualizations/dashboard-list/index.md
index dc523bf12c3..92e12996630 100644
--- a/docs/sources/panels-visualizations/visualizations/dashboard-list/index.md
+++ b/docs/sources/panels-visualizations/visualizations/dashboard-list/index.md
@@ -35,7 +35,7 @@ refs:
 
 Dashboard lists allow you to display dynamic links to other dashboards. You can configure the list to use starred dashboards, recently viewed dashboards, a search query, and dashboard tags.
 
-{{< figure src="/static/img/docs/v45/dashboard-list-panels.png" max-width="850px" alt="A dashboard list visualization" >}}
+{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-dashboard-list-v11.6.png" max-width="750px" alt="A dashboard list visualization" >}}
 
 On each dashboard load, this panel queries the dashboard list, always providing the most up-to-date results.
 
@@ -49,62 +49,53 @@ Once you’ve created a [dashboard](ref:dashboard), the following video shows yo
 
 {{< docs/play title="Dashboard List Visualization" url="https://play.grafana.org/d/fdlojrg7daebka/" >}}
 
-## Panel options
+## Configuration options
+
+{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
+
+### Panel options
 
 {{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
 
-## Dashboard list options
+### Dashboard list options
 
 Use the following options to refine your dashboard list visualization.
 
-### Include current time range
+<!-- prettier-ignore-start -->
 
-Select this option to propagate the time range of the current dashboard to the dashboard links. When you click a link, the linked dashboard opens with the indicated time range already set.
+| Option | Description |
+| ------ | ----------- |
+| Include current time range | Propagate the time range of the current dashboard to the dashboard list links. When you click a link, the linked dashboard opens with the indicated time range already set. |
+| Include current template variable values | Include template variables that are being used as query parameters in the dashboard list link. When you click the link, any matching templates in the linked dashboard are set to the values from the link. Learn more in [Dashboard URL variables](ref:dashboard-url-variables). |
+| Starred | Display starred dashboards in alphabetical order. |
+| Recently viewed | Display recently viewed dashboards in alphabetical order. |
+| Search | Display dashboards returned by search. You must enter at least one value in the search fields, **Query** or **Tags**. Variable interpolation is supported for both fields. For example, `$my_var` or `${my_var}`. |
+| Show headings | Headings for enabled sections are displayed. Sections are:<ul><li>**Starred**</li><li>**Recently viewed**</li><li>**Search**</li> |
+| Show folder names | Display the name of the folder where the dashboard is located. |
+| Max items | Set the maximum number of items to list per section. If you enter "10" and enable **Starred** and **Recently viewed** dashboards, the panel displays up to 20 total dashboards, 10 in each section. |
+| [Query](#query) | Search by dashboard name. This option is only applied when the **Search** switch is toggled on. |
+| [Folder](#folder) | Only dashboards from the selected folder are displayed in the dashboard list. This option is only applied when the **Search** switch is toggled on. |
+| [Tags](#tags) | Search by tags. This option is only applied when the **Search** switch is toggled on.  |
 
-### Include current template variable values
+<!-- prettier-ignore-end -->
 
-Select this option to include template variables that are being used as query parameters in a link. When you click the link, any matching templates in the linked dashboard are set to the values from the link. Learn more in [Dashboard URL variables](ref:dashboard-url-variables).
+#### Query
 
-### Starred
+Use this field to search by dashboard name. Query terms are case-insensitive and partial values are accepted.
+For example, if you have dashboards called "Indoor Temps" and "Outdoor temp", entering the word "temp" returns both results.
+This option is only applied when the **Search** switch is toggled on.
 
-Display starred dashboards in alphabetical order.
+#### Folder
 
-### Recently viewed
+Only dashboards from the selected folder are included in search results and displayed in the dashboard list.
+To include all dashboards in search results, select the top-level **Dashboards** folder.
+This option is only applied when the **Search** switch is toggled on.
 
-Display recently viewed dashboards in alphabetical order.
+#### Tags
 
-### Search
+Enter tags by which you want to search. Note that tags don't appear as you type, and they're case sensitive.
+Tag search uses an `OR` condition, so if a dashboard has one of the defined tags, it's included in the list.
 
-Display dashboards by search query or tags. You must enter at least one value in **Query** or **Tags**. For the **Query** and **Tags** fields, variable interpolation is supported. For example, `$my_var` or `${my_var}`. Learn more in [Search option](#search-options).
-
-### Show headings
-
-The selected list section is shown as a heading:
-
-- **Starred**
-- **Recently viewed**
-- **Search**
-
-### Max items
-
-Sets the maximum number of items to list per section. For example, if you leave this at the default value of 10 and select **Starred** and **Recently viewed** dashboards, then the panel displays up to 20 total dashboards, 10 in each section.
-
-## Search options
-
-These options only apply if you select the **Search** option.
-
-### Query
-
-Use this field to search by dashboard name. Query terms are case-insensitive and partial values are accepted. For example, if you have dashboards called "Indoor Temps" and "Outdoor temp", entering the word "temp" would return both results.
-
-### Folder
-
-Select the dashboard folders that you want to display.
-
-### Tags
-
-Enter tags by which you want to search. Note that tags don't appear as you type, and they're case sensitive. Tag search uses an `OR` condition, so if a dashboard has one of the defined tags, it's included in the list.
-
-{{< admonition type="note" >}}
 When multiple tags and strings appear, the dashboard list displays those matching _all_ conditions.
-{{< /admonition >}}
+
+This option is only applied when the **Search** switch is toggled on.