@grafana/create-plugin 7.13.0 → 7.15.0

package/templates/docs/common/workflows/validate-docs.yml

@@ -0,0 +1,52 @@
+name: Validate documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - '{{docsPath}}/**'
+      - 'src/plugin.json'
+      - 'package.json'
+{{#if lockFile}}
+      - '{{lockFile}}'
+{{/if}}
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - '{{docsPath}}/**'
+      - 'src/plugin.json'
+      - 'package.json'
+{{#if lockFile}}
+      - '{{lockFile}}'
+{{/if}}
+
+jobs:
+  validate:
+    name: Validate plugin docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+{{#if_eq packageManagerName "pnpm"}}
+      # pnpm action uses the packageManager field in package.json to
+      # understand which version to install.
+      - uses: pnpm/action-setup@v6
+{{/if_eq}}
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: '{{packageManagerName}}'
+
+      - name: Install dependencies
+        run: {{packageManagerInstallCmd}}
+
+      - name: Validate plugin documentation
+        run: {{packageManagerName}} run docs:validate

package/templates/docs/datasource/docs/AGENTS.md

@@ -0,0 +1,123 @@
+# Plugin docs
+
+This folder is the documentation for **{{{pluginName}}}**, published at
+`grafana.com/grafana/plugins/{{pluginId}}/docs/`.
+
+## Guides
+
+Read these before you write or change any page. This docs format is new and your training
+data does not cover it, so do not rely on what you know about other docs tools.
+
+Run `{{packageManagerName}} run docs:validate` and open the guide on its last line, `Docs guides:`. It's
+the guides' `index.md`, which says which guide to read for what, and the other guides sit next to it.
+The guides match the version of the validator this plugin uses. The line is a local path, usually
+`node_modules/@grafana/plugin-docs-cli/docs/index.md`, or a URL when the package isn't on disk, such as
+with Yarn Plug'n'Play.
+
+The guides name scripts such as `docs:validate`. This plugin uses **{{packageManagerName}}**, so run them
+with `{{packageManagerName}} run`, as in the commands below.
+
+## Pages and their source
+
+`annotations.md`, `alerting.md` and `dashboards.md` exist only when the plugin has that feature, as
+described under [Optional pages](#optional-pages).
+
+Files may have moved since the plugin was scaffolded, so trace them from `src/module.ts`.
+`new DataSourcePlugin<DataSource, Query, Options>(DataSource)` names the data source class, the query type
+and the options type, and `setConfigEditor` and `setQueryEditor` name the editor components.
+
+| Page                    | Source of truth                                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `index.md`              | Nothing - it is a curated router. Update it when pages are added or removed.                                                               |
+| `configure.md`          | The `setConfigEditor` component and the options type. With a backend, also how it reads these settings and its `CheckHealth` handler       |
+| `query-editor.md`       | The `setQueryEditor` component, the query type and the code that runs queries in the data source class or backend                          |
+| `template-variables.md` | Variable support in the data source class: `variables` or `metricFindQuery`, `applyTemplateVariables`, and `getTagKeys` and `getTagValues` |
+| `annotations.md`        | `annotations` support in the data source class                                                                                             |
+| `alerting.md`           | The backend's query handling, and what the data source class does to queries first, since alert rules skip it                              |
+| `dashboards.md`         | `includes` entries of type `dashboard` in `src/plugin.json` and their JSON files                                                           |
+| `troubleshooting.md`    | Error messages in source, known issues in the README or other docs and reported issues. Never guess failures                               |
+
+## Optional pages
+
+Add one of these pages when the plugin has the matching feature. Use the filename given here, give the page
+a `sidebar_position` that puts it where it belongs and link it from `index.md`.
+
+| Trigger                                            | Page             | Scope                                                            |
+| -------------------------------------------------- | ---------------- | ---------------------------------------------------------------- |
+| `"annotations": true` in `src/plugin.json`         | `annotations.md` | Annotation queries, the fields they return and examples.         |
+| `"alerting": true` in `src/plugin.json`            | `alerting.md`    | Which queries work in alert rules, creating a rule and examples. |
+| An `includes` entry of type `dashboard`            | `dashboards.md`  | What each bundled dashboard shows and how to import it.          |
+| Macros that outgrow a section of `query-editor.md` | `macros.md`      | Every macro with its syntax, what it expands to and an example.  |
+| RBAC role declarations in `src/plugin.json`        | `permissions.md` | What each role grants, default assignments.                      |
+
+## What not to write
+
+Never write installation instructions, such as installing the plugin with `grafana-cli`, from a zip file or
+in Docker. The Installation tab on the plugin page covers them, and these docs start from a plugin that is
+already installed. When the README has an installation section, leave it out of the pages.
+
+## Section briefs
+
+Each section of a scaffolded page has a brief telling you what belongs there. A brief is an HTML comment
+that starts with `section-brief`. Search the docs folder for `section-brief` to find what is left to write:
+
+```markdown
+## Macros
+
+<!-- section-brief
+Fill this in: A table of every macro the plugin expands in queries.
+
+If the plugin has no macros, remove this section entirely.
+-->
+```
+
+Some sections also have fixed text, with a brief that builds on it:
+
+```markdown
+## Create an alert rule
+
+To create an alert rule from a {{{pluginName}}} query:
+
+1. Navigate to **Alerting** > **Alert rules**.
+1. Click **New alert rule**.
+
+<!-- section-brief
+Fill this in: Continue the list above with the steps for the query and the alert condition.
+-->
+```
+
+Text outside a brief is written for every data source and is part of the scaffold. Keep it, and change it
+only where it's wrong for this plugin, such as a menu path or a step that differs.
+
+Everything inside a brief is the instruction. A brief covers the section it sits under, unless it says
+otherwise: it may tell you to extend the fixed text above it, to replace it with several sections or to
+remove the page. When a brief says to remove a section, remove its heading and fixed text too.
+
+To fill a section:
+
+1. Read the brief.
+2. Read the source the page documents, from the table above, then write the section.
+3. Delete the whole comment, from `<!-- section-brief` to `-->`.
+
+Briefs are not shown in the preview or the catalog, so a section you haven't written looks like a bare
+heading. `docs:validate` lists every section that still has only its brief.
+
+## Validate
+
+```bash
+{{packageManagerName}} run docs:validate
+```
+
+Run `docs:validate` after every page you write or change and fix what it reports. A docs task is done when
+it reports no warnings and no suggestions about section briefs. In particular, an `empty-section` or
+`unfilled-section-brief` suggestion means a section is still unwritten or a brief is still in place. Neither
+fails validation, so a passing exit code alone does not mean the docs are done.
+
+## Preview
+
+```bash
+{{packageManagerName}} run docs:serve    # local preview at http://localhost:3001, reloads on save
+```
+
+`docs:serve` keeps running until you stop it. Start it in the background if you need to look at the
+rendered pages, and stop it when you are done.

package/templates/docs/datasource/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/docs/datasource/docs/README.md

@@ -0,0 +1,20 @@
+# {{{pluginName}}} documentation
+
+This folder is the documentation for **{{{pluginName}}}**. It's published on the Documentation tab of
+`grafana.com/grafana/plugins/{{pluginId}}/` with each plugin release. This README isn't published.
+
+To learn how plugin docs work and how to write them, read the
+[Add documentation to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-docs) guide.
+
+## Next steps
+
+1. Fill in or review the pages. Each section has a note that says what belongs there.
+2. Add screenshots, videos and figures where they help readers. Save them inside this folder, for example in `img/`, and link to them with a relative path. `docs:validate` checks their formats and sizes.
+3. Run `{{packageManagerName}} run docs:serve` to preview the docs. It also lists every section left to fill.
+
+## Commands
+
+```bash
+{{packageManagerName}} run docs:serve     # local preview at http://localhost:3001
+{{packageManagerName}} run docs:validate  # check your docs, including sections left to fill
+```

package/templates/docs/datasource/docs/alerting.md

@@ -0,0 +1,56 @@
+---
+title: Alerting
+description: "Create Grafana alert rules from {{{yamlEscape pluginName}}} queries."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - alerting
+sidebar_position: 6
+---
+
+You can create alert rules that run {{{pluginName}}} queries on a schedule and fire when the result meets a condition, such as a value above a threshold. For general information about alerting, refer to [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/).
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Add bullets for what the reader needs in {{{pluginName}}} for alert queries to return data, such as read access, linking to `./configure.md`. If there is nothing to add, delete only this brief.
+-->
+
+## Query requirements
+
+<!-- section-brief
+Fill this in: Explain that a query must return numeric data: a time series reduced with **Reduce**, or a single numeric row. Say how to get a number otherwise, such as an aggregate or a **Count** over rows, and that each series becomes its own alert instance.
+
+If there are several query types, add a table of which work in alert rules. Alert rules run on the backend, so frontend-only query types don't. Mention the time filter macro, such as `$__timeFilter`.
+-->
+
+## Create an alert rule
+
+To create an alert rule from a {{{pluginName}}} query:
+
+1. Navigate to **Alerting** > **Alert rules**.
+1. Click **New alert rule**.
+1. Enter a **Name** for the rule.
+1. Select the **{{{pluginName}}}** data source.
+
+<!-- section-brief
+Fill this in: Continue the list with the query step, field labels in bold, then **Reduce** and **Threshold** expressions, evaluation behavior, labels and notifications, and saving. Link to `./query-editor.md` for the fields and to [Create a Grafana-managed alert rule](https://grafana.com/docs/grafana/latest/alerting/configure-alert-rules/create-grafana-managed-rule/) for the rest.
+-->
+
+## Limitations
+
+<!-- section-brief
+Fill this in: Add an H3 for each thing that works on a dashboard but not in an alert rule, and what to do instead. Alert rules skip the frontend data source class, so check `applyTemplateVariables`, `query()` overrides and ad hoc filters. Also check for auth that needs a signed-in user, such as forwarded OAuth, settings such as a row limit and API rate limits.
+
+If nothing applies, remove this section entirely.
+-->
+
+## Alert query examples
+
+<!-- section-brief
+Fill this in: Add an H3 for each realistic alert, such as on error counts or latency. Say what it watches for, show the query as a code block or as builder steps with field labels in bold, and end with the **Reduce** function and **Threshold** to use.
+
+Where it fits, add a no-data alert and one that combines two queries with a **Math** expression.
+-->

package/templates/docs/datasource/docs/annotations.md

@@ -0,0 +1,68 @@
+---
+title: Annotations
+description: "Mark events on your graphs with annotation queries from {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - annotations
+sidebar_position: 5
+---
+
+Annotations overlay event markers on time series panels, so you can correlate events from {{{pluginName}}}, such as deployments or incidents, with the metrics on your dashboards. For general information about annotations, refer to [Annotate visualizations](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/).
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Add bullets for what the reader needs in {{{pluginName}}} before annotation queries return anything, such as read access to the data, or events stored with a timestamp. Link to the matching section of `./configure.md` for access. If there is nothing beyond the configured data source, delete only this brief.
+-->
+
+## Create an annotation query
+
+To add an annotation query to a dashboard:
+
+1. Navigate to **Dashboard settings** > **Annotations**.
+1. Click **Add annotation query**.
+1. Enter a **Name** for the annotation.
+1. Select the **{{{pluginName}}}** data source.
+
+<!-- section-brief
+Fill this in: Continue the list above with the steps in the annotation editor, using its field labels in bold, and end with saving the dashboard.
+
+First find out which annotation editor the plugin has. If the data source class sets `annotations` to an `AnnotationSupport` object with its own `QueryEditor`, such as `this.annotations = createAnnotationSupport(this)`, the plugin has a custom annotation editor, so describe its fields here and its options under Annotation editor. If it sets `annotations = {}` or doesn't set it at all, Grafana uses the panel query editor followed by its standard field mapping, so link to `./query-editor.md` instead of repeating its fields.
+-->
+
+## Annotation editor
+
+<!-- section-brief
+Fill this in: Describe the custom annotation editor, from the `QueryEditor` set on `annotations` in the data source class. Add an H3 for each annotation type or preset it offers, saying when to use it, its fields and the query it generates. Say whether the generated query can be edited, and how the editor differs from the panel query editor. Also check `prepareAnnotation` and `processEvents` for behaviour the reader sees, such as defaults or how results become annotations.
+
+If the plugin has no custom annotation editor, remove this section entirely.
+-->
+
+## Query requirements
+
+<!-- section-brief
+Fill this in: Explain what an annotation query must return. With the standard field mapping, give this table and keep only the fields the plugin can return:
+
+| Field     | Required | Description |
+| --------- | -------- | ----------- |
+| `time`    | Yes      |             |
+| `timeEnd` | No       |             |
+| `title`   | No       |             |
+| `text`    | Yes      |             |
+| `tags`    | No       |             |
+
+Fields match by name. If there is no `time` field, Grafana uses the first time field, and if there is no `text` field, the first string field. A `timeEnd` field draws a region instead of a single marker. If a custom editor or `processEvents` maps fields differently, describe that mapping instead.
+
+If the editor has several query types, add a table of which ones suit annotations and why. Then say how to keep results to the dashboard time range, such as with the `$__timeFilter` macro, and note limits such as a result cap or API rate limits, and whether ad hoc filters also apply to annotation queries.
+-->
+
+## Annotation query examples
+
+<!-- section-brief
+Fill this in: Give realistic annotation queries for the events people mark with {{{pluginName}}}, such as deployments, incidents or errors, with an H3 for each. Say what each one marks and show the query the way a reader enters it, as a code block for a query language, or as steps with field labels in bold for a builder. Use the field names and syntax the editor really accepts.
+
+Include a region example with `timeEnd` if the plugin can return one, and an example that filters events with a dashboard variable if annotation queries interpolate variables.
+-->

package/templates/docs/datasource/docs/configure.md

@@ -0,0 +1,114 @@
+---
+title: Configure
+description: "Add the {{{yamlEscape pluginName}}} data source in Grafana and connect it to your service."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - configuration
+  - provisioning
+sidebar_position: 2
+---
+
+This document explains how to add and configure the {{{pluginName}}} data source in Grafana. After you configure the data source, refer to the [{{{pluginName}}} query editor](./query-editor.md) to start querying your data.
+
+## Before you begin
+
+Before you configure the data source, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can add data sources.
+
+<!-- section-brief
+Fill this in: Keep the list above. Add a bullet in the same **Label:** form for each other thing the reader needs: the instance of the service {{{pluginName}}} connects to and how Grafana reaches it, such as its address, default port and network access, and the credentials and permissions needed on it. If the service can sit behind a firewall, add a `> [!NOTE]` callout telling Grafana Cloud users to allowlist the Grafana Cloud outbound IP addresses, and link to https://grafana.com/docs/grafana-cloud/account-management/allow-traffic/.
+-->
+
+## Set up access in {{{pluginName}}}
+
+<!-- section-brief
+Fill this in: Steps the reader follows in the service {{{pluginName}}} connects to before adding the data source, such as creating a user, an API token or a cloud role. Take what's needed from the credential fields in the config editor, and work out the least access that works from what the backend calls, such as API endpoints, SQL statements or settings it changes. Say what fails if a permission is missing. Change the heading if necessary to name the task, such as "Create a read-only user". Leave the Grafana fields to Configure settings below.
+
+If the reader only needs credentials they already have, remove this section and keep them as a bullet in Before you begin.
+-->
+
+## Add the data source
+
+To add the {{{pluginName}}} data source:
+
+1. Click **Connections** in the left-side menu.
+1. Click **Add new connection**.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+1. Click **Add new data source**.
+
+## Configure settings
+
+<!-- section-brief
+Fill this in: An H3 for each section of the config editor, named and ordered as the editor shows them, such as Connection, Authentication, TLS or Additional settings. Under each H3, a table with this shape:
+
+| Setting | Description | Required |
+| ------- | ----------- | -------- |
+
+Start the first table with **Name** and **Default**. Use the field labels from the config editor, in bold. Find the settings in the config editor component and the options type, including `jsonData` and `secureJsonData`.
+
+In a description, say when a field only appears for some choice, such as a protocol, and when it affects another setting, such as a port that must change when TLS is turned on. If source shows the editor lacks an option readers expect, such as TLS settings, say so and what to do instead. For each authentication method, say when to use it. Use a `> [!NOTE]` callout for a method or setting that's only available in Grafana Cloud or Grafana Enterprise.
+
+When a feature needs more than a table row, such as forwarding OAuth identity or HTTP headers, or cloud provider auth like AWS SigV4, give it its own H2 after this section with its setup, requirements and behavior.
+-->
+{{#if hasBackend}}
+
+## Private data source connect
+
+<!-- section-brief
+Fill this in: Explain how to reach a service on a private network from Grafana Cloud with private data source connect (PDC), and link to https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/ for setup. Start with a `> [!NOTE]` callout saying PDC is only available in Grafana Cloud. Name the toggle the config editor shows, and say it only appears when the secure SOCKS proxy is enabled for the Grafana instance. For self-managed Grafana, show the setting that enables it:
+
+```ini
+[secure_socks_datasource_proxy]
+enabled = true
+```
+
+Keep this section only if the backend supports the secure SOCKS proxy (look for `EnableSecureSocksProxy` or `secureSocksProxyEnabled` in source). Otherwise, remove it entirely.
+-->
+{{/if}}
+
+## Verify the connection
+
+Click **Save & test** to verify the connection.
+
+<!-- section-brief
+Fill this in: Give the message the reader sees when the connection works and the most common failure messages, each with what it means. Take the messages from the health check in source (`CheckHealth` in the backend, or `testDatasource` in the frontend). Link failures to [troubleshooting](./troubleshooting.md) with a relative link.
+-->
+
+## Provision the data source
+
+You can provision the {{{pluginName}}} data source as code, with a Grafana provisioning file or with the Grafana Terraform provider.
+
+<!-- section-brief
+Fill this in: List the placeholders the examples below use, such as `<HOST>` or `<API_TOKEN>`, each with what to replace it with.
+-->
+
+### Provision with a configuration file
+
+You can define the data source in a YAML file as part of the Grafana provisioning system. For more information, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).
+
+<!-- section-brief
+Fill this in: A YAML example with this shape, using the real `jsonData` and `secureJsonData` keys from the options type and placeholders for every value the reader must supply:
+
+```yaml
+apiVersion: 1
+
+datasources:
+  - name: {{{pluginName}}}
+    type: {{pluginId}}
+    jsonData: {}
+    secureJsonData: {}
+```
+
+Follow it with a table of the keys it uses and what each one sets. Include `url`, `user` or other top-level fields only if the plugin reads them.
+-->
+
+### Provision with Terraform
+
+You can provision the data source with the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source) using the `grafana_data_source` resource.
+
+<!-- section-brief
+Fill this in: A Terraform example with `type = "{{pluginId}}"` that sets the same values as the YAML example. Pass `jsonData` through `json_data_encoded` and `secureJsonData` through `secure_json_data_encoded`, both wrapped in `jsonencode()`.
+-->

package/templates/docs/datasource/docs/dashboards.md

@@ -0,0 +1,28 @@
+---
+title: Dashboards
+description: "Import and use the dashboards that ship with {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - dashboards
+sidebar_position: 7
+---
+
+{{{pluginName}}} ships with ready-made dashboards that you can import and use as they are, or as a starting point for your own. For general information about dashboards, refer to [Dashboards](https://grafana.com/docs/grafana/latest/dashboards/).
+
+## Import a dashboard
+
+To import a dashboard that ships with {{{pluginName}}}:
+
+1. Click **Connections** > **Data sources** in the left-side menu.
+1. Select your {{{pluginName}}} data source.
+1. Click the **Dashboards** tab.
+1. Click **Import** next to the dashboard.
+
+Imported dashboards don't update when you upgrade the plugin. When a plugin upgrade ships a newer version of a dashboard, click **Update** next to it. This overwrites any changes you made to it.
+
+## Included dashboards
+
+<!-- section-brief
+Fill this in: One H3 per dashboard in the `includes` list of `src/plugin.json` whose `type` is `dashboard`, using its `name`. For each one, describe what it shows and what data or settings it needs to work, based on the panels and queries in its JSON file.
+-->

package/templates/docs/datasource/docs/index.md

@@ -0,0 +1,40 @@
+---
+title: Introduction
+description: "Where to start and what to read next in the {{{yamlEscape pluginName}}} docs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+sidebar_position: 1
+---
+
+<!-- section-brief
+Fill this in: Write a short orientation for someone who already has {{{pluginName}}} installed and landed here from the Documentation tab. One or two sentences on what this section covers and how it's organized. Do not restate what the data source connects to, its feature list or its requirements - that's the README's job on the Overview tab, and this reader has already seen it there. Do not list every page in this folder either - the sidebar already does that; use prose to say what to read first and why.
+-->
+
+## Recommended path
+
+<!-- section-brief
+Fill this in: Give a short, ordered reading path for someone new to {{{pluginName}}} - two or three sentences, not a repeat of the sidebar. Most readers need to connect the data source before anything else, e.g. "Start with **Configure** to connect {{{pluginName}}} to your service, then read **Query editor** to build your first query."
+-->
+
+## Common tasks
+
+<!-- section-brief
+Fill this in: List the jobs someone lands here to do, phrased as tasks rather than page titles, each linked to the page that answers it. For a typical data source plugin this might look like:
+
+- [Connect {{{pluginName}}} and choose an authentication method](./configure.md)
+- [Build and run a query](./query-editor.md)
+- [Make dashboards dynamic with template variables](./template-variables.md)
+{{#if hasAnnotations}}
+- [Mark events on your graphs with annotations](./annotations.md)
+{{/if}}
+{{#if hasAlerting}}
+- [Create alert rules from your queries](./alerting.md)
+{{/if}}
+{{#if hasDashboards}}
+- [Import the dashboards that ship with the plugin](./dashboards.md)
+{{/if}}
+- [Fix connection, authentication and query errors](./troubleshooting.md)
+
+Adapt this to {{{pluginName}}}'s actual entry points - add, remove or reword tasks so each one matches a real job a user comes here to do. This is a curated set of jobs, not a mechanical list of every file in this folder.
+-->

package/templates/docs/datasource/docs/query-editor.md

@@ -0,0 +1,72 @@
+---
+title: Query editor
+description: "Build and run queries with the {{{yamlEscape pluginName}}} query editor."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - query editor
+  - queries
+sidebar_position: 3
+---
+
+This document explains how to use the {{{pluginName}}} query editor to build queries and visualize {{{pluginName}}} data in Grafana dashboards.
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Keep the bullet above. Add a bullet for each other thing a reader needs before writing a query, such as read access to the data they query, a feature to enable on the target service or a query language to know. For access, link to the matching section of [configure](./configure.md). If there is nothing else, delete only this brief.
+-->
+
+## Editor modes
+
+<!-- section-brief
+Fill this in: An H3 for each mode the editor offers, such as a builder and a code editor, named as the editor names them. Say what each is for and when to use it, and how to switch between them. Add a screenshot of each mode when you can capture one, saved under `img/`. Never link an image that doesn't exist.
+
+If the editor has one mode, remove this section entirely.
+-->
+
+## Query types
+
+<!-- section-brief
+Fill this in: Document the fields the editor shows, in tables with this shape:
+
+| Field | Description |
+| ----- | ----------- |
+
+Use the field labels from the editor, in bold, and say which fields are required and their defaults and limits. If the editor has several query types or APIs, put the fields every type shares in a table first, then an H3 for each type that says when to use it and lists its own fields. Mention any shortcut that runs the query, such as **Shift+Enter**. Take the fields from the query editor component and the query type in source.
+
+If the editor has one query type, skip the H3s, give one table of its fields and rename the heading to "Query fields".
+-->
+
+## Format the query results
+
+<!-- section-brief
+Fill this in: Describe each result format the editor can return, such as time series, table, logs or traces, and say when to use each. For each format, say what the query must return for Grafana to show it, such as a `time` column plus at least one numeric column, sorted by time, and the column order that produces several series. Take the formats from the query editor and the code that builds data frames in source.
+
+If the editor has one result format, describe what the query must return in a paragraph without listing formats.
+-->
+{{#if hasBackend}}
+
+## Macros
+
+<!-- section-brief
+Fill this in: A table of every macro the plugin expands in queries, such as `$__timeFilter`, with this shape:
+
+| Macro | Description | Example |
+| ----- | ----------- | ------- |
+
+Macros are expanded in the backend, in the `QueryData` handler that implements `backend.QueryDataHandler`, or in code it calls. Take the macros from there, and show the syntax exactly as a reader writes it. Start with one example query that uses a macro. If a standard Grafana macro such as `$__timeGroup` doesn't work with this service, add a `> [!WARNING]` callout saying what to use instead.
+
+If the plugin has no macros, remove this section entirely.
+-->
+{{/if}}
+
+## Query examples
+
+<!-- section-brief
+Fill this in: Give realistic examples of the common query types from Query types, with an H3 for each type. If there is only one type, give examples for the jobs people use {{{pluginName}}} for instead. For each example, say what it does and show the query the way a reader enters it in the editor, using the field names and syntax the editor really accepts.
+
+Follow each example with the query as dashboard JSON stores it, a `targets` entry in a `json` code block. Take the shape from the query model in source and from any dashboard JSON under `provisioning/dashboards/`, and replace real UIDs and credentials with placeholders.
+-->

package/templates/docs/datasource/docs/template-variables.md

@@ -0,0 +1,69 @@
+---
+title: Template variables
+description: "Use template variables with {{{yamlEscape pluginName}}} to build dynamic, reusable dashboards."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - template variables
+sidebar_position: 4
+---
+
+Use template variables to create dynamic, reusable dashboards that let you change query parameters without editing individual panels. For general information about template variables, refer to [Templates and variables](https://grafana.com/docs/grafana/latest/dashboards/variables/).
+
+<!-- section-brief
+Fill this in: Delete only this brief.
+
+If the plugin supports no variable types and interpolates no variables in its queries, delete this page and its link in `index.md`.
+-->
+
+## Before you begin
+
+- [Configure the {{{pluginName}}} data source](./configure.md).
+- Understand [Grafana template variables](https://grafana.com/docs/grafana/latest/dashboards/variables/).
+- Know how to write queries in the [{{{pluginName}}} query editor](./query-editor.md).
+
+## Supported variable types
+
+The {{{pluginName}}} data source supports the following variable types:
+
+<!-- section-brief
+Fill this in: A table with a Yes or No for each variable type, in this order:
+
+| Variable type  | Supported |
+| -------------- | --------- |
+| Query          |           |
+| Custom         | Yes       |
+| Data source    | Yes       |
+| Ad hoc filters |           |
+
+Custom and Data source variables are handled by Grafana itself and work with every data source, so keep them as Yes. Query is Yes if the data source class sets `variables` or implements `metricFindQuery`. Ad hoc filters is Yes if it implements both `getTagKeys` and `getTagValues`.
+-->
+
+## Use variables in queries
+
+<!-- section-brief
+Fill this in: Explain how to use a variable in the {{{pluginName}}} query editor, field by field, since fields accept variables in different ways. For each field that accepts one, say how the reader adds it: picked from a drop-down that lists dashboard variables, perhaps with a prefix such as `var:`, or typed into an input or code editor as `$variable` or `${variable}`. Note fields that don't accept variables, and any difference between editor modes, such as a builder and a code editor. Give an example, and say how a single value is substituted, such as whether a string needs quotes. Say which Grafana global variables, such as `$__interval` or `$__from`, work and in which fields.
+
+Find which fields list variables in the query editor component, usually from `getTemplateSrv().getVariables()`, and which fields are interpolated in `applyTemplateVariables` or `interpolateVariablesInQueries`, or in the backend.
+
+If the plugin doesn't interpolate variables in its queries, remove this section entirely.
+-->
+
+## Query variables
+
+A query variable fills its drop-down by running a query against {{{pluginName}}}, so its options stay current with your data. Use one to let viewers pick a value, such as a host, a table or a project, and update every panel that uses it.
+
+To create a query variable:
+
+1. Navigate to **Dashboard settings** > **Variables**.
+1. Click **Add variable**.
+1. Select **Query** as the variable type.
+1. Select the **{{{pluginName}}}** data source.
+
+<!-- section-brief
+Fill this in: Continue the list above with the steps for the variable query editor, using its field labels in bold. Say whether it's the same editor as the query editor or a separate one, from the variable support in source.
+
+If the variable query editor has several query types, such as projects or environments, add an H3 for each that says what it lists, its fields and which part of each result becomes the display text and which the value. Otherwise, explain how the query result becomes the options: which column becomes the display text and which the value, and whether columns are matched by name, such as `text` and `value`, or by position, with one example for a single column and one for separate text and value. Take this from `metricFindQuery` or the variable support class in source.
+
+If the plugin doesn't support query variables, remove this whole section, including its heading and the text above.
+-->