@grafana/create-plugin 7.14.0 → 7.15.0

package/templates/docs/app/docs/configure.md

@@ -0,0 +1,65 @@
+---
+title: Configure
+description: "Change the {{{yamlEscape pluginName}}} settings in Grafana or provision them as code."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - configuration
+  - provisioning
+sidebar_position: 2
+---
+
+This document explains how to configure {{{pluginName}}} after you enable it.
+
+## Before you begin
+
+Before you configure the app, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can configure apps.
+- **The app enabled:** Follow [Enable the app](./index.md#enable-the-app).
+
+## Open the configuration page
+
+To open the {{{pluginName}}} configuration page:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+
+<!-- section-brief
+Fill this in: After the list above, add one sentence that names the tab to click, using the `title` of the page passed to `addConfigPage` in `src/module.ts(x)`, such as "Then click the **Configuration** tab." Keep it a sentence rather than another step of the list. If the app adds more than one config page, name each tab and what it holds.
+-->
+
+## Configure settings
+
+<!-- section-brief
+Fill this in: An H3 for each section of the config page, named and ordered as the page shows them, such as Connection, Authentication or Features. Under each H3, a table with this shape:
+
+| Setting | Description | Required |
+| ------- | ----------- | -------- |
+
+Use the field labels from the config page, in bold. If the config page has no settings of its own, such as when it only turns the app on or off, say so in one sentence and document what its buttons do instead of a table. Find the settings in the components passed to `addConfigPage` and the settings type, including `jsonData` and `secureJsonData`. In a description, say when a field only appears for some choice and when it affects another setting. Use a `> [!NOTE]` callout for a setting that's only available in Grafana Cloud or Grafana Enterprise.
+
+End with the button that saves the settings and what the reader sees when it works.
+-->
+
+## Provision the app
+
+You can provision {{{pluginName}}} as code with a Grafana provisioning file. For more information, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#plugins).
+
+<!-- section-brief
+Fill this in: A YAML example with this shape, using the real `jsonData` and `secureJsonData` keys from the settings type and placeholders for every value the reader must supply, such as `<API_URL>`:
+
+```yaml
+apiVersion: 1
+
+apps:
+  - type: {{pluginId}}
+    org_id: 1
+    disabled: false
+    jsonData: {}
+    secureJsonData: {}
+```
+
+Follow it with a table of the keys it uses and what each one sets, and list each placeholder with what to replace it with. If `provisioning/plugins/` has a file for the app, base the example on it.
+-->

package/templates/docs/app/docs/dashboards.md

@@ -0,0 +1,29 @@
+---
+title: Dashboards
+description: "Import and use the dashboards that ship with {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - dashboards
+sidebar_position: 6
+---
+
+{{{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 **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+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. When the app ships many dashboards, group related ones under a shared H3 and list them, rather than repeating the same description.
+-->

package/templates/docs/app/docs/index.md

@@ -0,0 +1,70 @@
+---
+title: Introduction
+description: "Set up {{{yamlEscape pluginName}}} and find what to read next in the docs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - setup
+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 app does or its feature list - 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.
+-->
+
+## Before you begin
+
+Before you set up the app, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can enable and configure apps.
+
+<!-- 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 Grafana version from `dependencies.grafanaDependency` in `src/plugin.json`, each plugin in `dependencies.plugins` linked to its catalog page at `https://grafana.com/grafana/plugins/<id>/`, and anything `src/plugin.json` doesn't declare, such as an external service, a telemetry pipeline or a license. Never cover installing the plugin itself, because the Installation tab on the plugin page owns it.
+-->
+
+## Enable the app
+
+To enable {{{pluginName}}}:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+1. Click **Enable**.
+
+<!-- section-brief
+Fill this in: If `src/plugin.json` sets `"autoEnabled": true`, the app is enabled when it's installed, so remove this section. Otherwise keep the steps above and remove only this brief.
+-->
+{{#if hasConfigPage}}
+
+After you enable the app, refer to [Configure](./configure.md) for its settings.
+{{/if}}
+
+## Connect your data
+
+<!-- section-brief
+Fill this in: The steps to get the data the app shows into Grafana, such as adding a data source, setting up an agent, setting environment variables or configuring a telemetry exporter. Take them from the README's setup sections and from what the app queries in source. Give each step the commands or settings to copy, and say how the reader can tell the data has arrived. Change the heading if necessary to name the task, such as "Add a data source". Never include steps to install the plugin itself, because the Installation tab on the plugin page owns them.
+
+If the app works without any setup of its own, remove this section entirely.
+-->
+
+## 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 app this might look like:
+
+{{#if hasConfigPage}}
+- [Change the app settings](./configure.md)
+{{/if}}
+{{#if defaultFeaturePage}}
+- [Find your way around {{{defaultFeaturePage.name}}}](./{{defaultFeaturePage.file}}.md)
+{{/if}}
+{{#if hasDashboards}}
+- [Import the dashboards that ship with the app](./dashboards.md)
+{{/if}}
+{{#if hasPermissions}}
+- [Give users access to the app](./permissions.md)
+{{/if}}
+- [Fix setup and data 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/app/docs/permissions.md

@@ -0,0 +1,45 @@
+---
+title: Permissions
+description: "The roles {{{yamlEscape pluginName}}} adds and the access it needs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - permissions
+  - RBAC
+sidebar_position: 7
+---
+
+This document explains who can use each part of {{{pluginName}}} and what the app can access. For general information, refer to [Role-based access control for app plugins](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/rbac-for-app-plugins/).
+
+## Roles
+
+<!-- section-brief
+Fill this in: A table with one row per entry in `roles` in `src/plugin.json`:
+
+| Role | Description | Granted by default to |
+| ---- | ----------- | --------------------- |
+
+Use the role's display name, or its name if it has none, and take the defaults from `grants`. After the table, say what each role lets a user do in the app, in terms of its pages and actions rather than the raw permission names.
+
+If `src/plugin.json` has no `roles`, remove this section and Assign a role below.
+-->
+
+## Page access
+
+<!-- section-brief
+Fill this in: A table of the app pages that need more than the `Viewer` role, with the role or permission each one needs, from the `role` and `action` of each `includes` entry in `src/plugin.json`. Link each page to its docs page.
+
+If no `includes` entry sets `role` or `action`, remove this section.
+-->
+
+## What the app can access
+
+<!-- section-brief
+Fill this in: A table of the permissions in `iam.permissions` in `src/plugin.json`, with the action, the scope and why the app needs it, based on what the backend does with that access. Administrators read this before they install the app, so be precise.
+
+If `src/plugin.json` has no `iam`, remove this section.
+-->
+
+## Assign a role
+
+To assign a role to a user, team or service account, refer to [Assign RBAC roles](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/assign-rbac-roles/).

package/templates/docs/app/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+---
+title: Troubleshooting
+description: "Troubleshoot common {{{yamlEscape pluginName}}} setup, data and access errors."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - troubleshooting
+sidebar_position: 8
+---
+
+This page explains how to fix common issues when you set up or use {{{pluginName}}}. For setup instructions, refer to the [Introduction](./index.md).
+
+<!-- section-brief
+Fill this in: Never guess failures. Each symptom must come from an error or empty-state message in source, a known issue in the README or other docs or a reported issue. When source holds only a few real failures, a short page is right, so don't pad it.
+
+Replace this brief with one H2 per category that has real failures, in this order:
+
+- `## Setup errors`: the app won't enable, or its settings don't save or don't connect.
+- `## Missing data`: pages that load but show no data, linking to the setup steps in the [Introduction](./index.md).
+{{#if hasPermissions}}
+- `## Permission errors`: users who can't see a page or an action, linking to [Permissions](./permissions.md).
+{{/if}}
+- `## Performance issues`: slow pages, timeouts or rate limits, and the settings that help.
+
+Add an H2 for another part of the app with real failures, named after that part.
+
+Open each H2 with one sentence on when its errors occur. Add an H3 per symptom, named after the error message in quotes, such as `### "Failed to load services"`, then **Symptoms:** and a **Possible causes and solutions:** table, or a numbered **Solutions:** list for a single cause.
+-->
+
+## Get more detail about an error
+
+For errors in the app, open the developer tools in your browser and check the console.
+{{#if hasBackend}}
+
+In self-managed Grafana, you can also find more detail in the Grafana server logs:
+
+1. Set the log level to `debug` in the Grafana configuration file:
+
+   ```ini
+   [log]
+   level = debug
+   ```
+
+1. Restart Grafana and reproduce the error.
+1. Look for log lines with `logger=plugin.{{{pluginId}}}`.
+1. Set the log level back to `info` when you're done, to keep the logs small.
+{{/if}}
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker and the docs of any service the app depends on to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The app page where it happens and the relevant app settings, with credentials removed.

package/templates/docs/app/feature-page.md

@@ -0,0 +1,26 @@
+---
+title: "{{{yamlEscape page.name}}}"
+description: "Use the {{{yamlEscape page.name}}} page in {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - "{{{yamlEscape page.name}}}"
+sidebar_position: {{page.position}}
+---
+
+<!-- section-brief
+Fill this in: One or two sentences on what the {{{page.name}}} page is for and when someone opens it. The app shows it at `{{{page.path}}}`. Pair it with a screenshot of the page if `info.screenshots` in `src/plugin.json` has one.
+-->
+{{#if page.role}}
+
+## Before you begin
+
+- **Grafana permissions:** At least the `{{page.role}}` role.
+
+<!-- section-brief
+Fill this in: Keep the bullet above. Add a bullet in the same **Label:** form only for something the reader needs before they can use this page and wouldn't guess, such as a feature flag that must be on or data that must exist. Never repeat setup from the Introduction or from another page, and don't link back to them. If this section would only point at another page, it adds nothing, so remove it, including its heading and the bullet above.
+-->
+{{/if}}
+
+<!-- section-brief
+Fill this in: Replace this brief with one H2 per task someone does on the {{{page.name}}} page, named after the task, such as "Filter by service" or "Compare two time ranges". Under each, give the steps with the UI labels in bold, and say what each part of the page shows when it helps the task. Find the tasks in the component that renders `{{{page.path}}}`, including its tabs and drilldowns, which `src/plugin.json` doesn't list. Describe UI that only appears behind a feature flag or a condition as "when X is enabled".
+-->

package/templates/docs/app/features-index.md

@@ -0,0 +1,12 @@
+---
+title: Features
+description: "What each part of {{{yamlEscape pluginName}}} is for."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+sidebar_position: {{position}}
+---
+
+<!-- section-brief
+Fill this in: One line per page in this folder, in the order the app's navigation shows them, each linked to its page and saying what the reader does there. This is a router, so keep the detail on the pages themselves.
+-->

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.
+-->