Docs: Rename/move 'introduction' to 'key concepts' and fix broken lin…

…ks (#926)

Co-authored-by: Esteban Beltran <[email protected]>
Co-authored-by: Jack Westbrook <[email protected]>
Co-authored-by: Timur Olzhabayev <[email protected]>
Co-authored-by: Levente Balogh <[email protected]>
Co-authored-by: David Harris <[email protected]>

.github/workflows/test-build.yml

@@ -27,13 +27,10 @@ jobs:
   build-docs:
     needs: changes
     if: ${{ needs.changes.outputs.docs == 'true' }}
-    runs-on: ubuntu-latest
-    env:
-      NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
-      NX_BRANCH: ${{ github.event.number || github.ref_name }}
+    runs-on: ubuntu-latest    
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v4        
       - name: Setup node
         uses: actions/setup-node@v4
         with:
@@ -43,4 +40,4 @@ jobs:
       - name: Install dependencies
         run: npm ci
       - name: Build documentation website (Dev Portal)
-        run: npm run docs:build
+        run: npm run build -w website

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

@@ -19,7 +19,7 @@ Is something missing from this list? [Let us know](https://github.com/grafana/pl
 ## General
 
 - **Verify that your data source or app plugin can be provisioned** - Refer to [Provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources) for more information.
-- **Include default dashboards in your data source or app plugin** - Refer to [Bundling of dashboards](https://grafana.com/developers/plugin-tools/introduction/plugin-types-usage#bundling-of-dashboards) for more information.
+- **Include default dashboards in your data source or app plugin** - Refer to [Bundling of dashboards](../../key-concepts/plugin-types-usage#bundling-of-dashboards) for more information.
 - **Ensure that the minimum version of Grafana is correct** - Make sure that the `grafanaDependency` in your `plugin.json` points to the earliest version of Grafana that your plugin fully supports.
 - **Don't expose sensitive information** - For security reasons, avoid exposing sensitive information such as secrets. Make sure to utilize log levels properly, avoid excessive logging, and never log credentials or other sensitive information.
 - **Avoid using `console.log` in your plugin** - Console messages are usually for debugging purposes and therefore not suitable to ship to the client.
@@ -39,7 +39,7 @@ Is something missing from this list? [Let us know](https://github.com/grafana/pl
 
 - **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.
 - **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](/introduction/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 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).
 - **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).
@@ -49,14 +49,14 @@ Is something missing from this list? [Let us know](https://github.com/grafana/pl
 
 ### 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](/introduction/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](/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.
 
 ### 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](/introduction/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).
+- **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).
-- **Keep cached connections** - This is an important optimization. To learn more, refer to our [documentation](/introduction/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).
+- **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.
 - **Don't use the local file system** - Different plugins share the same environment. For security reasons, plugins shouldn't rely on local files.

docusaurus/docs/create-a-plugin/develop-a-plugin/panel-properties.md

@@ -17,7 +17,7 @@ sidebar_position: 5
 
 # Subscribe to Grafana events
 
-If you’re building a [panel plugin](../../introduction/plugin-types-usage.md#panel-visualization-plugins), in some cases you may want your plugin to react to changes that occur outside of your plugin. For example, you may want your plugin to react when the user zooms in or out of another panel. In this guide, you’ll learn how to make your plugin react to events in Grafana.
+If you’re building a [panel plugin](../../key-concepts/plugin-types-usage.md#panel-visualization-plugins), in some cases you may want your plugin to react to changes that occur outside of your plugin. For example, you may want your plugin to react when the user zooms in or out of another panel. In this guide, you’ll learn how to make your plugin react to events in Grafana.
 
 :::tip
 

docusaurus/docs/create-a-plugin/develop-a-plugin/work-with-backend.md

@@ -15,7 +15,8 @@ Develop backend components for a Grafana plugin in [Go](https://go.dev/). The fo
 
 ## Update the Go SDK
 
-To keep the [Grafana plugin SDK for Go](../../introduction/grafana-plugin-sdk-for-go) up to date:
+To keep the [Grafana plugin SDK for Go](../../key-concepts/backend-plugins/grafana-plugin-sdk-for-go) up to date:
+To keep the [Grafana plugin SDK for Go](../../key-concepts/backend-plugins/grafana-plugin-sdk-for-go) up to date:
 
 ```bash
 go get -u github.com/grafana/grafana-plugin-sdk-go

docusaurus/docs/create-a-plugin/develop-a-plugin/work-with-data-frames.md

@@ -13,7 +13,7 @@ sidebar_position: 3
 
 # Work with data frames
 
-The [data frame](../../introduction/data-frames.md) is a columnar data structure that allows for efficient querying of large amounts of data. Since data frames are a central concept when developing plugins for Grafana, in this guide we'll look at some ways you can use them.
+The [data frame](../../key-concepts/data-frames) is a columnar data structure that allows for efficient querying of large amounts of data. Since data frames are a central concept when developing plugins for Grafana, in this guide we'll look at some ways you can use them.
 
 The `DataFrame` interface contains a `name` and an array of `fields` where each field contains the name, type, and the values for the field.
 

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

@@ -306,7 +306,7 @@ While the data source proxy supports the most common authentication methods for
 - Proxy routes only support HTTP or HTTPS.
 - Proxy routes don't support custom token authentication.
 
-If any of these limitations apply to your plugin, you need to add a [backend plugin](../../introduction/backend-plugins). Because backend plugins run on the server, they can access decrypted secrets, which makes it easier to implement custom authentication methods.
+If any of these limitations apply to your plugin, you need to add a [backend plugin](../../key-concepts/backend-plugins/#caching-and-connection-pooling). Because backend plugins run on the server, they can access decrypted secrets, which makes it easier to implement custom authentication methods.
 
 The decrypted secrets are available from the `DecryptedSecureJSONData` field in the instance settings.
 

docusaurus/docs/create-a-plugin/extend-a-plugin/add-logs-metrics-traces-for-backend-plugins.md

@@ -70,7 +70,7 @@ You can log multiple messages and include certain key-value pairs without repeat
 
 **Example:**
 
-The following example illustrates how you can instantiate a logger per [datasource instance](../../introduction/plugin-types-usage.md#usage-of-data-source-plugins), and use the `With` method to include certain key-value pairs over the life-time of this datasource instance.
+The following example illustrates how you can instantiate a logger per [datasource instance](../../key-concepts/plugin-types-usage#usage-of-data-source-plugins), and use the `With` method to include certain key-value pairs over the life-time of this datasource instance.
 
 ```go
 package plugin
@@ -298,7 +298,7 @@ For further details and an up-to-date list of what metrics are automatically gat
 
 ### Implement metrics in your plugin
 
-The [Grafana plugin SDK for Go](../../introduction/grafana-plugin-sdk-for-go.md) uses the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang). Any custom metric registered with the [default registry](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#pkg-variables) will be picked up by the SDK and exposed through the [Collect metrics capability](../../introduction/backend.md#collect-metrics).
+The [Grafana plugin SDK for Go](../../key-concepts/backend-plugins/grafana-plugin-sdk-for-go) uses the [Prometheus instrumentation library for Go applications](https://github.com/prometheus/client_golang). Any custom metric registered with the [default registry](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#pkg-variables) will be picked up by the SDK and exposed through the [Collect metrics capability](../../key-concepts/backend-plugins/#collect-metrics).
 
 For convenience, it's recommended to use the [promauto package](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/promauto) when creating custom metrics since it automatically registers the metric in the [default registry](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#pkg-variables) and exposes them to Grafana.
 

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

@@ -14,7 +14,7 @@ keywords:
 
 # Add resource handler for data source plugins
 
-You can add a resource handler to your data source backend to extend the Grafana HTTP API with your own data source-specific routes. This guide explains why you may want to add [resource](/introduction/backend-plugins#resources) handlers and some common ways for doing so.
+You can add a resource handler to your data source backend to extend the Grafana HTTP API with your own data source-specific routes. This guide explains why you may want to add [resource](/key-concepts/backend-plugins/#resources) handlers and some common ways for doing so.
 
 ## Uses of resource handlers
 
@@ -81,7 +81,7 @@ props.datasource.postResource('device', { state: "on" });
 
 ## Advanced use cases
 
-If you have some more advanced use cases or want to use a more Go-agnostic approach for handling resources, you can use the regular [`http.Handler`](https://pkg.go.dev/net/http#Handler). You can do so by using a package provided by the [Grafana Plugin SDK for Go](../../introduction/grafana-plugin-sdk-for-go.md) named [`httpadapter`](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/backend/resource/httpadapter). This package provides support for handling resource calls using an [`http.Handler`](https://pkg.go.dev/net/http#Handler).
+If you have some more advanced use cases or want to use a more Go-agnostic approach for handling resources, you can use the regular [`http.Handler`](https://pkg.go.dev/net/http#Handler). You can do so by using a package provided by the [Grafana Plugin SDK for Go](../../key-concepts/backend-plugins/grafana-plugin-sdk-for-go) named [`httpadapter`](https://pkg.go.dev/github.com/grafana/grafana-plugin-sdk-go/backend/resource/httpadapter). This package provides support for handling resource calls using an [`http.Handler`](https://pkg.go.dev/net/http#Handler).
 
 Using [`http.Handler`](https://pkg.go.dev/net/http#Handler) allows you to also use Go’s built-in router functionality called [`ServeMux`](https://pkg.go.dev/net/http#ServeMux) or your preferred HTTP router library (for example, [`gorilla/mux`](https://github.com/gorilla/mux)).
 

docusaurus/docs/e2e-test-a-plugin/test-a-data-source-plugin/configuration-editor.md

@@ -18,7 +18,7 @@ Most data source plugins need authentication to communicate with third-party ser
 
 ### Testing the configuration in a backend data source plugin
 
-Backend data sources implement a [health check](../../introduction/backend.md#health-checks) endpoint that is used to test whether the configuration is valid or not. In the following example, the configuration editor form is populated with valid values then the `Save & test` button is clicked. Clicking `Save & test` calls the Grafana backend to save the configuration, then passes configuration to the plugin's backend health check endpoint. The test will be successful only if both calls yields a successful status code.
+Backend data sources implement a [health check](../../key-concepts/backend-plugins/#health-checks) endpoint that is used to test whether the configuration is valid or not. In the following example, the configuration editor form is populated with valid values then the `Save & test` button is clicked. Clicking `Save & test` calls the Grafana backend to save the configuration, then passes configuration to the plugin's backend health check endpoint. The test will be successful only if both calls yields a successful status code.
 
 ```ts title="configurationEditor.spec.ts"
 import { test, expect } from '@grafana/plugin-e2e';

docusaurus/docs/e2e-test-a-plugin/test-a-data-source-plugin/index.md

@@ -12,6 +12,6 @@ keywords:
 sidebar_position: 10
 ---
 
-The following articles will give some tips and tricks on how to test data source plugins, including example tests to cover common scenarios. To write end-to-end tests similar to the ones in this guide, you'll need your data source to be configured using provisioning. If you haven't already checked out our guide on how to [setup the resources](../setup-resources.md) you'll need, do that first.
+The following articles give some tips and tricks on how to test data source plugins, including example tests to cover common scenarios. To write end-to-end tests similar to the ones in this guide, you'll need your data source to be configured using provisioning. If you haven't already checked out our guide on how to [set up the required resources](../setup-resources.md), do that first.
 
 <DocLinkList />