Website: Update Docusaurus to v3 (#519)

grafana · Nov 10, 2023 · 3a39732 · 3a39732
1 parent ef7378f
commit 3a39732
Show file tree

Hide file tree

Showing 20 changed files with 6,838 additions and 2,633 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,7 +12,7 @@ Thank you, Joan López de la Franca Beltran ([@joanlopez](https://github.com/joa
 #### 🐛 Bug Fix
 
 - `@grafana/create-plugin@2.6.0`
-  - Create Plugin: Replace 'master' with 'main' on  ref [#507](https://github.com/grafana/plugin-tools/pull/507) ([@joanlopez](https://github.com/joanlopez))
+  - Create Plugin: Replace 'master' with 'main' on ref [#507](https://github.com/grafana/plugin-tools/pull/507) ([@joanlopez](https://github.com/joanlopez))
 
 #### Authors: 2
 

diff --git a/docusaurus/docs/create-a-plugin/develop-a-plugin/set-up-github-workflows.md b/docusaurus/docs/create-a-plugin/develop-a-plugin/set-up-github-workflows.md
@@ -22,7 +22,7 @@ The CI (`ci.yml`) workflow is designed to lint, type check, and build the fronte
 
 ## The release workflow
 
-:::caution
+:::warning
 
 This workflow requires a Grafana Cloud API key. Before you begin, follow the instructions for [distributing your plugin](../../publish-a-plugin/publish-or-update-a-plugin.md).
 

diff --git a/docusaurus/docs/create-a-plugin/develop-a-plugin/work-with-frontend.mdx b/docusaurus/docs/create-a-plugin/develop-a-plugin/work-with-frontend.mdx
@@ -13,7 +13,7 @@ sidebar_position: 1
 
 Develop the frontend component of a Grafana plugin in Typescript with ReactJS as the View library. Several commands are available within the `plugin` directory for interacting with the frontend.
 
-:::caution
+:::warning
 We [do not support](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/) plugins written in Angular.
 :::
 

diff --git a/...s/create-a-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md b/...s/create-a-plugin/extend-a-plugin/add-authentication-for-data-source-plugins.md
@@ -32,13 +32,13 @@ Configure your data source plugin to authenticate against a third-party API in o
 
 ## Encrypt data source configuration
 
-Data source plugins have two ways of storing custom configuration: `jsonData` and `secureJsonData`. 
+Data source plugins have two ways of storing custom configuration: `jsonData` and `secureJsonData`.
 
 Users with the Viewer role can access data source configuration such as the contents of `jsonData` in cleartext. If you've enabled anonymous access, anyone who can access Grafana in their browser can see the contents of `jsonData`.
 
-Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions). You can see the settings that the current user has access to by entering `window.grafanaBootData` in the developer console of your browser. 
+Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions). You can see the settings that the current user has access to by entering `window.grafanaBootData` in the developer console of your browser.
 
-:::caution
+:::danger
 
 Do not use `jsonData` with sensitive data such as password, tokens, and API keys. If you need to store sensitive information, use `secureJsonData` instead.
 
@@ -148,11 +148,11 @@ To forward requests through the Grafana proxy, you need to configure one or more
    ]
    ```
 
-  :::note
+:::note
 
-  You need to restart the Grafana server every time you make a change to your `plugin.json` file.
+You need to restart the Grafana server every time you make a change to your `plugin.json` file.
 
-  :::
+:::
 
 1. In the `DataSource`, extract the proxy URL from `instanceSettings` to a class property called `url`:
 

diff --git a/docusaurus/docs/introduction/manage-npm-dependencies.md b/docusaurus/docs/introduction/manage-npm-dependencies.md
@@ -46,7 +46,7 @@ To share dependencies, Grafana defines two key components:
 - **[SystemJS](https://github.com/systemjs/systemjs) import map in Grafana:** The dependency must be listed in a SystemJS import map in the Grafana application.
 - **Plugin build tool configuration:** The dependency must be externalized in the plugin's build tool configuration, which is primarily done using Webpack.
 
-:::caution
+:::danger
 
 Customizing the build tool configuration to change the external dependencies is not supported and will likely lead to plugin loading failure or bugs.
 

diff --git a/docusaurus/docs/introduction/plugin-lifecycle.md b/docusaurus/docs/introduction/plugin-lifecycle.md
@@ -16,13 +16,13 @@ sidebar_position: 2.5
 
 # Life cycle of a plugin
 
-This document describes the various phases of a plugin such as installation and loading. We will describe the differences in a plugin's life cycle depending on its type and whether or not it has a [backend](backend.md).  
+This document describes the various phases of a plugin such as installation and loading. We will describe the differences in a plugin's life cycle depending on its type and whether or not it has a [backend](backend.md).
 
 ## Installing and uninstalling a plugin
 
 For instructions to install or uninstall plugins, see our documentation at [Plugin administration](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-grafana-plugins).
 
-Upon installation, a plugin is extracted to the _plugin directory_ on the filesystem. Similarly, uninstalling a plugin deletes the files from the same directory.  
+Upon installation, a plugin is extracted to the _plugin directory_ on the filesystem. Similarly, uninstalling a plugin deletes the files from the same directory.
 
 :::note
 
@@ -32,9 +32,9 @@ Use of the Grafana CLI to install or uninstall a plugin requires you to restart
 
 ## Loading plugins
 
-Plugins are loaded either when Grafana starts up or when a plugin has been installed/uninstalled during runtime. 
+Plugins are loaded either when Grafana starts up or when a plugin has been installed/uninstalled during runtime.
 
-Understanding the different phases involved when Grafana is loading a plugin may help you better understand plugin usage and [troubleshoot](#troubleshooting) any unexpected behavior. For example, why a certain plugin is not marked as installed in the plugins catalog or for use within Grafana even though you've installed it. 
+Understanding the different phases involved when Grafana is loading a plugin may help you better understand plugin usage and [troubleshoot](#troubleshooting) any unexpected behavior. For example, why a certain plugin is not marked as installed in the plugins catalog or for use within Grafana even though you've installed it.
 
 For [backend](./backend.md) plugins, there is an additional initialization process (see [Phase 3](#phase-3-backend-plugin-initialization)).
 
@@ -44,14 +44,15 @@ The life cycle of plugins is tracked in-memory and is not persisted in Grafana
 
 :::
 
-### Phase 1. Plugin discovery 
+### Phase 1. Plugin discovery
 
 Grafana starts to discover which plugins are installed by scanning directories on the file system for every `plugin.json`.
 
-### Phase 2. Plugin loading 
+### Phase 2. Plugin loading
 
 All plugins that were discovered in the discovery phase are checked to make sure they’re valid. Some of the automated checks include:
-- Plugins must have a valid [signature](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-signatures). Valid plugins are referred to as _verified plugins_. 
+
+- Plugins must have a valid [signature](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-signatures). Valid plugins are referred to as _verified plugins_.
 - Angular detection: Given that [Angular is deprecated](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/), if Angular support is disabled and Angular is detected in the plugin, then we record an error and don't allow the plugin to be loaded.
 
 ### Phase 3. Backend plugin initialization
@@ -66,17 +67,17 @@ Registered plugins show as installed in the catalog and appear in views for sele
 
 ### Phase 5. Start backend plugin
 
-For registered plugins that have a backend, Grafana starts to run the backend binary as a separate process using HashiCorp’s Go Plugin System over RPC. The supported plugin protocol and version is negotiated between Grafana (client) and the plugin (server) to give Grafana an understanding of the plugin's capabilities. 
+For registered plugins that have a backend, Grafana starts to run the backend binary as a separate process using HashiCorp’s Go Plugin System over RPC. The supported plugin protocol and version is negotiated between Grafana (client) and the plugin (server) to give Grafana an understanding of the plugin's capabilities.
 
-A Grafana backend plugin has its own separate life cycle. So long as the backend plugin is running, Grafana will make sure to restart the backend plugin in case it crashes or is terminated. When Grafana is shut down, the backend processes is then terminated.  
+A Grafana backend plugin has its own separate life cycle. So long as the backend plugin is running, Grafana will make sure to restart the backend plugin in case it crashes or is terminated. When Grafana is shut down, the backend processes is then terminated.
 
-### Phase 6. Client-side loading 
+### Phase 6. Client-side loading
 
-After Grafana has started and the [HTTP API](https://grafana.com/docs/grafana/latest/developers/http_api/) is running, Grafana users receive the server-side rendered index page containing so-called bootstrap data. This data includes the list of available plugins and a URI to a `module.js` file that Grafana uses to instantiate the plugin. 
+After Grafana has started and the [HTTP API](https://grafana.com/docs/grafana/latest/developers/http_api/) is running, Grafana users receive the server-side rendered index page containing so-called bootstrap data. This data includes the list of available plugins and a URI to a `module.js` file that Grafana uses to instantiate the plugin.
 
-When the user interacts with a UI that requires a plugin, Grafana will _lazy load_ the plugin's `module.js` file: 
+When the user interacts with a UI that requires a plugin, Grafana will _lazy load_ the plugin's `module.js` file:
 
-- **Panel plugins** - When the user opens a dashboard with panels (or interacts with any UI that requires a plugin), Grafana lazy-loads the necessary plugin’s code through a fetch request. Each plugin is loaded only once but its objects are initialized multiple times. 
+- **Panel plugins** - When the user opens a dashboard with panels (or interacts with any UI that requires a plugin), Grafana lazy-loads the necessary plugin’s code through a fetch request. Each plugin is loaded only once but its objects are initialized multiple times.
 
 - **Data-source plugins** - A data-source plugin could be loaded in more than one way. For instance, it could be loaded in the Explore page if the user selects the data source in the dropdown, or if they load a dashboard containing a plugin data source.
 

diff --git a/docusaurus/docs/migration-guides/migrate-from-toolkit.mdx b/docusaurus/docs/migration-guides/migrate-from-toolkit.mdx
@@ -9,7 +9,7 @@ keywords:
   - plugin
   - toolkit
   - Grafana toolkit
-  - migrating 
+  - migrating
 ---
 
 import MigrateNPM from '@snippets/createplugin-migrate.npm.md';
@@ -18,7 +18,7 @@ import MigrateYarn from '@snippets/createplugin-migrate.yarn.md';
 
 The `@grafana/toolkit` tool is now [deprecated](https://grafana.com/docs/grafana/next/breaking-changes/breaking-changes-v10-0/#grafanatoolkit-cli-commands-have-been-removed-and-migrated-to-the-create-plugin-package). If you are still using `@grafana/toolkit` to scaffold and develop plugins, follow this guide to make the jump to our newest plugin tools.
 
-:::caution
+:::warning
 Our plugin tools use ReactJS. We [do not support](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/) plugins written in Angular.
 :::
 

diff --git a/docusaurus/docs/migration-guides/update-create-plugin-versions.mdx b/docusaurus/docs/migration-guides/update-create-plugin-versions.mdx
@@ -57,6 +57,6 @@ Note that if there are no dependencies then you will not see this prompt.
 
 Select 'y' to update any npm scripts in the `package.json` file to match the latest configurations. Any scripts that previously used `grafana-toolkit` are replaced.
 
-:::caution
+:::warning
 We strongly recommend that you consult the [changelog](https://github.com/grafana/plugin-tools/blob/main/CHANGELOG.md) for potential breaking changes before making changes to your configuration.
 :::
diff --git a/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md b/docusaurus/docs/publish-a-plugin/publish-or-update-a-plugin.md
@@ -19,7 +19,7 @@ In this guide you learn how to manage the lifecycle of a plugin in the catalog,
 
 ## Before you begin
 
-- [Review our guidelines](https://grafana.com/legal/plugins/#plugin-publishing-and-signing-criteria) - Learn about the Grafana Labs criteria for publishing and signing plugins. 
+- [Review our guidelines](https://grafana.com/legal/plugins/#plugin-publishing-and-signing-criteria) - Learn about the Grafana Labs criteria for publishing and signing plugins.
 - [Package a plugin](./package-a-plugin.md) - Build the plugin and get it ready to share in the form of a ZIP archive.
 - Refer to [plugin-examples](https://github.com/grafana/grafana-plugin-examples) to review best practices for building your plugin.
 
@@ -53,10 +53,10 @@ Follow these steps to publish your plugin for the first time.
    All submissions are manually inspected by a plugin reviewer.
    For every new plugin, we perform a manual review that includes the following checks:
 
-    - **Code review:** For quality and security purposes, we review the source code for the plugin.
-    - **Tests:** We install your plugin on one of our Grafana instances to test it for basic use.
-      We may ask you to assist us in configuring a test environment for the plugin.
-      We use the test environment whenever you submit a plugin update.
+   - **Code review:** For quality and security purposes, we review the source code for the plugin.
+   - **Tests:** We install your plugin on one of our Grafana instances to test it for basic use.
+     We may ask you to assist us in configuring a test environment for the plugin.
+     We use the test environment whenever you submit a plugin update.
 
 ## Update your plugin
 

diff --git a/docusaurus/docs/tutorials/build-a-logs-data-source-plugin.md b/docusaurus/docs/tutorials/build-a-logs-data-source-plugin.md
@@ -12,7 +12,6 @@ keywords:
   - datasource
 ---
 
-
 # Build a logs data source plugin
 
 Grafana data source plugins support metrics, logs, and other data types. The steps to build a logs data source plugin are largely the same as for a metrics data source, but there are a few differences which we will explain in this guide.
@@ -46,13 +45,13 @@ Tell Grafana that your data source plugin can return log data, by adding `"logs"
 
 The log data frame should include following fields:
 
-| Field name     | Field type                                      | Required field | Description                                                                                                                                                                                                                                   |
-| -------------- | ----------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **timestamp**  | `time`                                          | required       | Timestamp, non-nullable.                                                                                                                                                                                                                      |
-| **body**       | `string`                                        | required       | Content of the log line, non-nullable.                                                                                                                                                                                                        |
-| **severity**   | `string`                                        | optional       | Severity/level of the log line. If no severity field is found, consumers/client will decide the log level. More information about log levels, refer to [Logs integration](https://grafana.com/docs/grafana/latest/explore/logs-integration/). |
-| **id**         | `string`                                        | optional       | Unique identifier of the log line.                                                                                                                                                                                                            |
-| **labels** | `json raw message` (Go) or `other` (TypeScript) | optional       | Additional labels of the log line. Other systems may refer to this with different names, such as "attributes". Represent its value as Record<string,any> type in JavaScript.                                                          |
+| Field name    | Field type                                      | Required field | Description                                                                                                                                                                                                                                   |
+| ------------- | ----------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **timestamp** | `time`                                          | required       | Timestamp, non-nullable.                                                                                                                                                                                                                      |
+| **body**      | `string`                                        | required       | Content of the log line, non-nullable.                                                                                                                                                                                                        |
+| **severity**  | `string`                                        | optional       | Severity/level of the log line. If no severity field is found, consumers/client will decide the log level. More information about log levels, refer to [Logs integration](https://grafana.com/docs/grafana/latest/explore/logs-integration/). |
+| **id**        | `string`                                        | optional       | Unique identifier of the log line.                                                                                                                                                                                                            |
+| **labels**    | `json raw message` (Go) or `other` (TypeScript) | optional       | Additional labels of the log line. Other systems may refer to this with different names, such as "attributes". Represent its value as `Record<string,any>` type in JavaScript.                                                                |
 
 Logs data frame's `type` needs to be set to `type: DataFrameType.LogLines` in data frame's meta.
 
@@ -135,7 +134,7 @@ const result = createDataFrame({
 
 :::note
 
-This feature must be implemented in the data frame as a meta attribute. 
+This feature must be implemented in the data frame as a meta attribute.
 
 :::
 

diff --git a/docusaurus/docs/ui-extensions/create-an-extension-point.md b/docusaurus/docs/ui-extensions/create-an-extension-point.md
@@ -33,7 +33,7 @@ Finally, consider if there is any information from the current view that should
 
 Use the `getPluginLinkExtensions` method in `@grafana/runtime` to create an extension point within your plugin.
 
-:::warning
+:::danger
 
 When you create an extension point in a plugin, you create a public interface for other plugins to interact with. Changes to the extension point ID or its context could break any plugin that attempts to register a link inside your plugin.
 

diff --git a/docusaurus/website/docusaurus.config.base.js b/docusaurus/website/docusaurus.config.base.js
@@ -2,6 +2,10 @@ const path = require('path');
 const remarkFigureCaption = require('gridsome-remark-figure-caption');
 const { grafanaPrismTheme } = require('./src/theme/prism');
 
+const customFields = {
+  nodeEnv: process.env.NODE_ENV,
+};
+
 /** @type {import('@docusaurus/types').Config} */
 const generalConfig = {
   title: 'Grafana Plugin Tools',
@@ -21,7 +25,7 @@ const generalConfig = {
   i18n: {
     defaultLocale: 'en',
     locales: ['en'],
-  },  
+  },
 };
 
 const plugins = [
@@ -127,6 +131,7 @@ const themeConfigFooter = {
 
 const themeConfigPrism = {
   theme: grafanaPrismTheme,
+  additionalLanguages: ['bash', 'diff', 'json'],
 };
 
 const themeConfigColorMode = {
@@ -136,6 +141,7 @@ const themeConfigColorMode = {
 };
 
 module.exports = {
+  customFields,
   generalConfig,
   plugins,
   presetsDocs,

diff --git a/docusaurus/website/docusaurus.config.dev.js b/docusaurus/website/docusaurus.config.dev.js
@@ -1,6 +1,7 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 const {
+  customFields,
   generalConfig,
   plugins,
   presetsDocs,
@@ -65,6 +66,7 @@ const config = {
   },
 
   customFields: {
+    ...customFields,
     rudderStackTracking: {
       url: 'https://rs.grafana-dev.com',
       writeKey: '1w02fcWseyqcwsJA9CSKRkfEOfU',