Docs: Reorganization of data source how-to files

docusaurus/docs/create-a-plugin/_category_.json

@@ -1,5 +1,5 @@
 {
-  "position": 20,
+  "position": 21,
   "label": "Create a plugin",
   "customProps": {
     "description": "Guides for taking your plugin from bare essentials to robustly feature-enabled."

docusaurus/docs/create-a-plugin/develop-a-plugin/best-practices.md

@@ -37,25 +37,25 @@ Is something missing from this list? [Let us know](https://github.com/grafana/pl
 
 ## Data source plugins
 
-- **If your plugin needs to store credentials, use `secureJsonData` instead of `jsonData`** - The former is encrypted at rest while the latter isn't. Refer to [Secure JSON data](/create-a-plugin/extend-a-plugin/add-authentication-for-data-source-plugins#store-configuration-in-securejsondata) for more information.
+- **If your plugin needs to store credentials, use `secureJsonData` instead of `jsonData`** - The former is encrypted at rest while the latter isn't. Refer to [Secure JSON data](/how-to-guides/data-source-plugins/add-authentication#store-configuration-in-securejsondata) for more information.
 - **Implement a query builder** - This is highly useful for users who are not familiar with the query language of the data source. Refer, for example, to the [Query Builder for Microsoft SQL Server](https://grafana.com/docs/grafana/latest/datasources/mssql/query-editor/#builder-mode) which helps write SQL queries for that service.
 - **Add a health check for your plugin** - [Health checks](../../key-concepts/backend-plugins/#health-checks) are used to verify that the data source is working properly. How this is implemented depends on whether the plugin has a backend. Refer to our examples for health checks in the [frontend](https://github.com/grafana/grafana-plugin-examples/blob/5441fe2f818e28cdeb06eb7066ff198dd34bb0ab/examples/datasource-http/src/DataSource.ts#L81-L115) and [backend](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/datasource-basic/pkg/plugin/datasource.go#L77). For the `backend` case, it's not necessary to modify its frontend code as long as it extends the [`DataSourceWithBackend`](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/datasource-basic/src/datasource.ts#L5) class from `@grafana/runtime`.
-- **Add [dashboard variables](https://grafana.com/docs/grafana/latest/dashboards/variables/) support** - Dashboard (or template) variables allow users to create dynamic dashboards. There are two aspects of adding support for variables in your plugin. The first is allowing queries for your data source and return values to be used as variables. The second is replacing existing variables in other queries. For more information, refer to our [documentation](/create-a-plugin/extend-a-plugin/add-support-for-variables#add-support-for-query-variables-to-your-data-source). Pay special attention when selecting "All values" since it may require specific logic to join variable values.
-- **Add annotations support** - Annotations allow users to add contextual information to their dashboards and it's possible to use queries to define them. For more information, refer to [Enable annotations](/create-a-plugin/extend-a-plugin/enable-for-annotations).
+- **Add [dashboard variables](https://grafana.com/docs/grafana/latest/dashboards/variables/) support** - Dashboard (or template) variables allow users to create dynamic dashboards. There are two aspects of adding support for variables in your plugin. The first is allowing queries for your data source and return values to be used as variables. The second is replacing existing variables in other queries. For more information, refer to our [documentation](../../how-to-guides/data-source-plugins/add-support-for-variables#add-support-for-query-variables-to-your-data-source). Pay special attention when selecting "All values" since it may require specific logic to join variable values.
+- **Add annotations support** - Annotations allow users to add contextual information to their dashboards and it's possible to use queries to define them. For more information, refer to [Enable annotations](../../how-to-guides/data-source-plugins/add-annotations).
 - **Practice good front-end design** - When building frontend components, make sure to use [Grafana components](https://developers.grafana.com/ui/latest/index.html?path=/docs/docs-overview-intro--page) as the base and follow the [Saga Design System](https://grafana.com/developers/saga/about/overview).
-- **Add query editor help** - Query editors can be complex and it's useful to provide help to users. For more information, refer to [Add query editor help](/create-a-plugin/extend-a-plugin/add-query-editor-help).
+- **Add query editor help** - Query editors can be complex and it's useful to provide help to users. For more information, refer to [Add query editor help](../../how-to-guides/data-source-plugins/add-query-editor-help.md).
 - **Skip hidden or empty queries** - This avoids executing unnecessary or wrong queries. Data sources implementing [`DataSourceWithBackend`](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/datasource-basic/src/datasource.ts#L5) only need to implement the method `filterQuery`. Refer to this [example](https://github.com/grafana/grafana/blob/fd5f66083c91b9759ae7772f99b80c9342b93290/public/app/plugins/datasource/loki/datasource.ts#L1085).
 - **Specify a default query** - Default queries can help users to discover how queries are written for the plugin. Refer to this [example](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b/examples/datasource-streaming-backend-websocket/streaming-backend-websocket-plugin/src/datasource.ts#L39-L41).
 
 ### Frontend (only) plugins
 
-- **Data sources running only on the frontend typically use the [Grafana proxy](/create-a-plugin/extend-a-plugin/add-authentication-for-data-source-plugins#add-a-proxy-route-to-your-plugin) to access an external service** - This is a simple way of adding support for queries in your plugin, and it doesn't require Golang knowledge. However, there are use cases for which writing a backend plugin is necessary. Refer to [Backend plugins](../../key-concepts/backend-plugins/#use-cases-for-implementing-a-backend-plugin) for more information about those.
+- **Data sources running only on the frontend typically use the [Grafana proxy](/how-to-guides/data-source-plugins/add-authentication#add-a-proxy-route-to-your-plugin) to access an external service** - This is a simple way of adding support for queries in your plugin, and it doesn't require Golang knowledge. However, there are use cases for which writing a backend plugin is necessary. Refer to [Backend plugins](../../key-concepts/backend-plugins/#use-cases-for-implementing-a-backend-plugin) for more information about those.
 
 ### Backend plugins
 
 - **Add support for alerting** - Backend plugins have inherent support for [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) but this support needs to be enabled. Simply add `"alerting": true` to your `plugin.json` file.
 - **Use the `CallResourceHandler` interface to serve custom HTTP requests**. For more information, refer to [Resource handlers](../../key-concepts/backend-plugins/#resources). This is useful, for example, when providing query builders, as shown in this [example](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/app-with-backend/pkg/plugin/app.go#L35).
-- **Add logs, metrics and traces to your data source.** Make it easier to diagnose and resolve issues for both plugin developers and Grafana operators. Find more information in our [documentation](/create-a-plugin/extend-a-plugin/add-logs-metrics-traces-for-backend-plugins).
+- **Add logs, metrics and traces to your data source.** Make it easier to diagnose and resolve issues for both plugin developers and Grafana operators. Find more information in our [documentation](../../how-to-guides/data-source-plugins/add-logs-metrics-traces).
 - **Keep cached connections** - This is an important optimization. To learn more, refer to our [documentation](../../key-concepts/backend-plugins/#caching-and-connection-pooling) and an [example](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/datasource-http-backend/pkg/plugin/datasource.go#L40-L66).
 - **Add macro support** - Macros are similar to variables, but they are typically evaluated in the backend and can return values based on environment data like the current time selection. It can be useful, for example, to evaluate alerts during a dynamic period. These are usually defined using the syntax `$__macroName` (for example, `$__timeFilter`). Refer to this [example](https://github.com/grafana/grafana-plugin-examples/blob/0532f8b23645251997088ac7a1707a72d3fd9248/examples/datasource-basic/pkg/query/macro.go) to discover how you can implement support. Some pre-defined macros are available in the [plugin SDK `macros` package](https://github.com/grafana/grafana-plugin-sdk-go/tree/main/experimental/macros).
 - **For SQL data sources, refer to the [`sqlutil` package in the SDK](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/data/sqlutil)** - It includes multiple helpers to work with SQL data sources for things like data frame conversion, default macros, and so on. Also, consider using the [`sqlds` package](https://pkg.go.dev/github.com/grafana/sqlds) which highly simplifies the implementation of SQL data sources.

docusaurus/docs/create-a-plugin/extend-a-plugin/add-resource-handler.md

@@ -18,7 +18,7 @@ You can add a resource handler to your data source backend to extend the Grafana
 
 ## Uses of resource handlers
 
-The primary way for a data source to retrieve data from a backend is through the [query method](./add-query-editor-help.md). But sometimes your data source needs to request data on demand; for example, to offer auto-completion automatically inside the data source’s query editor.
+The primary way for a data source to retrieve data from a backend is through the [query method](../../how-to-guides/data-source-plugins/add-query-editor-help). But sometimes your data source needs to request data on demand; for example, to offer auto-completion automatically inside the data source’s query editor.
 
 Resource handlers are also useful for building control panels that allow the user to write back to the data source. For example, you could add a resource handler to update the state of an IoT device.
 

docusaurus/docs/create-a-plugin/extend-a-plugin/add-router.md

@@ -81,4 +81,4 @@ func (d *MyDatasource) handleQueryFallback(ctx context.Context, req *backend.Que
 An example of using [`QueryTypeMux`](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/backend/datasource#QueryTypeMux) can be found for Grafana's built-in TestData data source. Refer to this code for examples of implementation:
 
 - [create query type multiplexer](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/testdata.go#L22) and [calls registerScenarios](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/testdata.go#L44)
-- [registerScenarios method](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/scenarios.go#L33) uses a [helper method](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/scenarios.go#L204-L207) to register each query type handler. The latter also shows how you can wrap the actual handler in another handler to apply common functionality or middleware to all handlers. For example, logging and traces. 
+- [registerScenarios method](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/scenarios.go#L33) uses a [helper method](https://github.com/grafana/grafana/blob/623ee3a2be5c4cd84c61b6bbe82a32d18cc29828/pkg/tsdb/grafana-testdata-datasource/scenarios.go#L204-L207) to register each query type handler. The latter also shows how you can wrap the actual handler in another handler to apply common functionality or middleware to all handlers. For example, logging and traces.

docusaurus/docs/create-a-plugin/extend-a-plugin/fetch-data-from-frontend.md

@@ -249,7 +249,7 @@ const response = getBackendSrv().fetch<TODO[]>({
 
 ## Add authentication to your requests using the data proxy
 
-To learn about adding authentication to the data proxy, refer to our [documentation](./add-authentication-for-data-source-plugins.md).
+To learn about adding authentication to the data proxy, refer to our [documentation](../../how-to-guides/data-source-plugins/add-authentication-for-data-source-plugins.md).
 
 ## Debug requests from the data proxy
 
@@ -271,4 +271,4 @@ With this configuration, the Grafana server output shows the requests going out
 
 ## Send special headers using the data proxy
 
-You can send special headers using the data proxy. To learn about adding headers to the data proxy, refer to our [documentation](./add-authentication-for-data-source-plugins.md).
+You can send special headers using the data proxy. To learn about adding headers to the data proxy, refer to our [documentation](../../how-to-guides/data-source-plugins/add-annotations-for-data-source-plugins.md).

docusaurus/docs/how-to-guides/_category_.json

@@ -0,0 +1,9 @@
+{
+  "position": 21,
+  "label": "How-to guides",
+  "customProps": {
+    "description": "Learn how to perform common tasks with Grafana plugins."
+  },
+  "collapsible": true,
+  "collapsed": true
+}

docusaurus/docs/how-to-guides/data-source-plugins/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Data source plugins",
+  "customProps": {
+    "description": "Learn how to perform tasks in Grafana data source plugin development."
+  },
+  "collapsible": true,
+  "collapsed": true
+}

docusaurus/docs/create-a-plugin/extend-a-plugin/enable-annotations.md → docusaurus/docs/how-to-guides/data-source-plugins/add-annotations-for-data-source-plugins.md

@@ -1,16 +1,14 @@
 ---
-id: enable-for-annotations
-title: Enable annotations
-description: Add support for annotations in your plugin.
+id: add-annotations
+title: Add annotations
+description: Add support for annotations in your data source plugin.
 keywords:
   - grafana
   - plugins
   - plugin
   - annotations
 ---
 
-# Enable annotations
-
 You can add support to your plugin for annotations that will insert information into Grafana alerts. This guide explains how to add support for [annotations](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/) to a data source plugin.
 
 ## Support annotations in your data source plugin

docusaurus/docs/create-a-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md → docusaurus/docs/how-to-guides/data-source-plugins/add-authentication-for-data-source-plugins.md

@@ -1,6 +1,6 @@
 ---
-id: add-authentication-for-data-source-plugins
-title: Add authentication for data source plugins
+id: add-authentication
+title: Add authentication
 description: How to add authentication for data source plugins.
 keywords:
   - grafana
@@ -11,8 +11,6 @@ keywords:
   - datasource
 ---
 
-# Add authentication for data source plugins
-
 Grafana plugins can perform authenticated requests against a third-party API by using the _data source proxy_ or through a custom a _backend plugin_.
 
 ## Choose an authentication method

docusaurus/docs/create-a-plugin/extend-a-plugin/add-support-for-explore-queries.md → docusaurus/docs/how-to-guides/data-source-plugins/add-features-for-explore-queries.md

@@ -1,6 +1,6 @@
 ---
-id: add-support-for-explore-queries
-title: Add features to Explore queries
+id: add-features-for-explore-queries
+title: Add features for Explore queries
 description: Add features to Explore queries in Grafana plugin development.
 keywords:
   - grafana
@@ -11,8 +11,6 @@ keywords:
   - explore
 ---
 
-# Add features to Explore queries
-
 [Explore](https://grafana.com/docs/grafana/latest/explore/) allows users can make ad-hoc queries without the use of a dashboard. This is useful when they want to troubleshoot or learn more about the data.
 
 Your data source supports Explore by default and uses the existing query editor for the data source. This guide explains how to extend functionality for Explore queries in a data source plugin.

docusaurus/docs/create-a-plugin/extend-a-plugin/add-logs-metrics-traces-for-backend-plugins.md → docusaurus/docs/how-to-guides/data-source-plugins/add-logs-metrics-traces-for-backend-plugins.md

@@ -1,6 +1,6 @@
 ---
-id: add-logs-metrics-traces-for-backend-plugins
-title: Add logs, metrics and traces for backend plugins
+id: add-logs-metrics-traces
+title: Add logs, metrics, and traces
 description: How to add logs, metrics and traces for backend plugins.
 keywords:
   - grafana
@@ -16,8 +16,6 @@ keywords:
   - back-end
 ---
 
-# Add logs, metrics and traces for backend plugins
-
 Adding [logs](#logs), [metrics](#metrics) and [traces](#traces) for backend plugins makes it easier to diagnose and resolve issues for both plugin developers and Grafana operators. This document provides guidance, conventions and best practices to help you effectively instrument your plugins, as well as how to access this data when the plugin is installed.
 
 ## Logs
@@ -114,7 +112,7 @@ Use a contextual logger to automatically include additional key-value pairs atta
 
 :::note
 
-Make sure you are using at least [grafana-plugin-sdk-go v0.186.0](https://github.com/grafana/grafana-plugin-sdk-go/releases/tag/v0.186.0). See [Update the Go SDK](../develop-a-plugin/work-with-backend#update-the-go-sdk) for update instructions.
+Make sure you are using at least [grafana-plugin-sdk-go v0.186.0](https://github.com/grafana/grafana-plugin-sdk-go/releases/tag/v0.186.0). Refer to [Update the Go SDK](../../key-concepts/backend-plugins/grafana-plugin-sdk-for-go) for update instructions.
 
 :::
 
@@ -396,7 +394,7 @@ If tracing is disabled in Grafana, `backend.DefaultTracer()` returns a no-op tra
 
 :::note
 
-Make sure you are using at least [`grafana-plugin-sdk-go v0.157.0`](https://github.com/grafana/grafana-plugin-sdk-go/releases/tag/v0.157.0). Refer to [Update the Go SDK](../develop-a-plugin/work-with-backend#update-the-go-sdk) for update instructions.
+Make sure you are using at least [`grafana-plugin-sdk-go v0.157.0`](https://github.com/grafana/grafana-plugin-sdk-go/releases/tag/v0.157.0). Refer to [Update the Go SDK](../../create-a-plugin/develop-a-plugin/work-with-backend) for update instructions.
 
 :::
 

docusaurus/docs/create-a-plugin/extend-a-plugin/add-query-editor-help.md → docusaurus/docs/how-to-guides/data-source-plugins/add-query-editor-help.md

@@ -11,8 +11,6 @@ keywords:
   - query editor help
 ---
 
-# Add query editor help
-
 Query editors support the addition of a help component to display examples of potential queries. When the user clicks on one of the examples, the query editor is automatically updated. This helps the user to make faster queries.
 
 1. In the `src` directory of your plugin, create a file `QueryEditorHelp.tsx` with the following content:

docusaurus/docs/create-a-plugin/extend-a-plugin/add-support-for-variables.md → docusaurus/docs/how-to-guides/data-source-plugins/add-support-for-variables.md

@@ -10,8 +10,6 @@ keywords:
   - variables
 ---
 
-# Add support for variables
-
 Variables are placeholders for values, and you can use them to create templated queries, and dashboard or panel links. For more information on variables, refer to [Templates and variables](https://grafana.com/docs/grafana/latest/dashboards/variables).
 
 In this guide, you'll see how you can turn a query string like this: