@grafana/create-plugin 7.15.1 → 7.16.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [7.16.0](https://github.com/grafana/plugin-tools/compare/@grafana/create-plugin@7.15.1...@grafana/create-plugin@7.16.0) (2026-10-22)
+
+
+### Features
+
+* **create-plugin:** Override the default Grafana version in the experimental-app-sdk addition ([#3014](https://github.com/grafana/plugin-tools/issues/3014)) ([8d35cd5](https://github.com/grafana/plugin-tools/commit/8d35cd55d2213b454f8e465ec7b9e01cc3039010))
+* **create-plugin:** scaffold docs snippets with fallback text ([#3021](https://github.com/grafana/plugin-tools/issues/3021)) ([7ef65e4](https://github.com/grafana/plugin-tools/commit/7ef65e418a9ed5951d62184954511297196aa0ee))
+
 ## [7.15.1](https://github.com/grafana/plugin-tools/compare/@grafana/create-plugin@7.15.0...@grafana/create-plugin@7.15.1) (2026-10-21)
 
 

package/dist/codemods/additions/prompts/docs-content.md

@@ -20,7 +20,7 @@ This usually runs once, after `add docs`. Running it again is safe, because it o
 
 ## Check first
 
-Search the docs folder for `section-brief` comments. A section that still has its brief is yours to write. A section without one has been written by the author, so never rewrite it.
+Search the docs folder for `section-brief` comments. A section that still has its brief is yours to write. A section without one has been written by the author, so never rewrite it. Text between `<!-- snippet:... -->` and `<!-- /snippet:... -->` markers is maintained by Grafana, so never edit inside a snippet.
 
 If no briefs remain, the pages are already written. Do steps 1 and 3, adding any README or linked-docs content that isn't on the pages yet without rewriting what is there, then steps 7 to 10. If nothing is left to migrate, say so in the summary and change nothing.
 

package/dist/codemods/additions/scripts/experimental-app-sdk.js

@@ -36,6 +36,7 @@ function appSdk(context) {
   referenceAgentInstructions(context, data);
   addGenerateScript(context);
   addFeatureToggle(context);
+  addGrafanaVersionOverride(context);
   wireGoBackend(context, data);
   if (Object.keys(context.listChanges()).length > changesBefore) {
     context.setMessage(buildNextStepsMessage(hasGoBackend(context), data.packageManagerName));
@@ -155,6 +156,45 @@ function addFeatureToggle(context) {
   composeData.setIn(["services", "grafana", "environment", "GF_FEATURE_TOGGLES_ENABLE"], toggles.join(","));
   context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
 }
+const GRAFANA_BUILD_ARGS = {
+  grafana_image: "${GRAFANA_IMAGE:-grafana}",
+  grafana_version: "${GRAFANA_VERSION:-nightly}"
+};
+function addGrafanaVersionOverride(context) {
+  const composePath = "docker-compose.yaml";
+  const composeContent = context.getFile(composePath);
+  if (!composeContent) {
+    additionsDebug(`Could not find ${composePath}. Skipping the Grafana version override.`);
+    return;
+  }
+  const composeData = parseDocument(composeContent);
+  if (!(composeData.getIn(["services", "grafana"]) instanceof YAMLMap)) {
+    additionsDebug(`Could not find the grafana service in ${composePath}. Skipping the Grafana version override.`);
+    return;
+  }
+  const build = composeData.getIn(["services", "grafana", "build"]);
+  if (build !== void 0 && !(build instanceof YAMLMap)) {
+    additionsDebug(`services.grafana.build in ${composePath} is not a mapping. Skipping the Grafana version override.`);
+    return;
+  }
+  const args = composeData.getIn(["services", "grafana", "build", "args"]);
+  if (args !== void 0 && !(args instanceof YAMLMap)) {
+    additionsDebug(
+      `services.grafana.build.args in ${composePath} is not a mapping. Skipping the Grafana version override.`
+    );
+    return;
+  }
+  let changed = false;
+  for (const [name, value] of Object.entries(GRAFANA_BUILD_ARGS)) {
+    if (!composeData.hasIn(["services", "grafana", "build", "args", name])) {
+      composeData.setIn(["services", "grafana", "build", "args", name], value);
+      changed = true;
+    }
+  }
+  if (changed) {
+    context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
+  }
+}
 function wireGoBackend(context, data) {
   if (!hasGoBackend(context)) {
     additionsDebug("No Go backend found. Skipping main.go wiring.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/create-plugin",
-  "version": "7.15.1",
+  "version": "7.16.0",
   "repository": {
     "type": "git",
     "directory": "packages/create-plugin",
@@ -43,6 +43,7 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
+    "@grafana/plugin-docs-parser": "0.6.0",
     "@libs/find-up": "1.0.0",
     "@libs/output": "1.0.3",
     "@libs/version": "1.0.2",

package/src/codemods/additions/prompts/docs-content.md

@@ -20,7 +20,7 @@ This usually runs once, after `add docs`. Running it again is safe, because it o
 
 ## Check first
 
-Search the docs folder for `section-brief` comments. A section that still has its brief is yours to write. A section without one has been written by the author, so never rewrite it.
+Search the docs folder for `section-brief` comments. A section that still has its brief is yours to write. A section without one has been written by the author, so never rewrite it. Text between `<!-- snippet:... -->` and `<!-- /snippet:... -->` markers is maintained by Grafana, so never edit inside a snippet.
 
 If no briefs remain, the pages are already written. Do steps 1 and 3, adding any README or linked-docs content that isn't on the pages yet without rewriting what is there, then steps 7 to 10. If nothing is left to migrate, say so in the summary and change nothing.
 

package/src/codemods/additions/scripts/docs.test.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
+import { readSnippets, renderSnippet } from '@grafana/plugin-docs-parser';
 import * as v from 'valibot';
 import { parse as parseYaml } from 'yaml';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -77,6 +78,7 @@ const PAGES_BY_TYPE: Record<string, string[]> = {
   app: ['index', 'configure', 'overview', 'reports', 'dashboards', 'permissions', 'troubleshooting'],
 };
 const PLUGIN_TYPES = Object.keys(PAGES_BY_TYPE);
+const SNIPPET_MARKER_RE = /^<!-- \/?snippet:\S+ -->$/gm;
 
 // scaffolds once and writes it to disk, so the re-run sees a plugin that is already fully set up
 function scaffoldThenRerun(
@@ -749,7 +751,7 @@ describe('docs codemod', () => {
         const content = context.getFile(`docs/${page}.md`) ?? '';
         const briefs = content.match(/<!-- section-brief\n[\s\S]*?-->/g) ?? [];
         expect(briefs.length, page).toBeGreaterThan(0);
-        expect(content.match(/<!--/g)?.length, page).toBe(briefs.length);
+        expect(content.replace(SNIPPET_MARKER_RE, '').match(/<!--/g)?.length, page).toBe(briefs.length);
         expect(content, page).not.toContain('section-brief:');
       }
     });
@@ -829,7 +831,7 @@ describe('docs codemod', () => {
         troubleshooting: [
           'This page explains how to fix common issues when you configure or use the My Plugin data source. For setup instructions, refer to [Configure the My Plugin data source](./configure.md).',
           'To see the raw request and response for a panel, open the panel editor and click **Query inspector**.',
-          'In self-managed Grafana, you can also find more detail in the Grafana server logs:',
+          'In self-managed Grafana, the Grafana server logs show more detail:',
           "1. Set the log level to `debug` in the Grafana configuration file:\n\n   ```ini\n   [log]\n   level = debug\n   ```\n\n1. Restart Grafana and reproduce the error.\n1. Look for log lines with `logger=plugin.acme-test-datasource`.\n1. Set the log level back to `info` when you're done, to keep the logs small.",
           "If this page doesn't solve your problem:",
           '- Search the [Grafana community forums](https://community.grafana.com/).\n- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.',
@@ -867,7 +869,7 @@ describe('docs codemod', () => {
         troubleshooting: [
           'This page explains how to fix common issues when you set up or use My Plugin. For setup instructions, refer to the [Introduction](./index.md).',
           'For errors in the app, open the developer tools in your browser and check the console.',
-          'In self-managed Grafana, you can also find more detail in the Grafana server logs:',
+          'In self-managed Grafana, the Grafana server logs show more detail:',
           "1. Set the log level to `debug` in the Grafana configuration file:\n\n   ```ini\n   [log]\n   level = debug\n   ```\n\n1. Restart Grafana and reproduce the error.\n1. Look for log lines with `logger=plugin.acme-test-app`.\n1. Set the log level back to `info` when you're done, to keep the logs small.",
           "If this page doesn't solve your problem:",
           '- Search the [Grafana community forums](https://community.grafana.com/).\n- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.',
@@ -886,6 +888,7 @@ describe('docs codemod', () => {
           let left = (context.getFile(`docs/${page}.md`) ?? '')
             .replace(/^---\n[\s\S]*?\n---\n/, '')
             .replace(/<!-- section-brief\n[\s\S]*?-->/g, '')
+            .replace(SNIPPET_MARKER_RE, '')
             .replace(/^#{1,6} .*$/gm, '');
           for (const text of FIXED_TEXT[type][page] ?? []) {
             expect(left, page).toContain(text);
@@ -896,6 +899,39 @@ describe('docs codemod', () => {
       }
     );
 
+    // when the parser's text for a snippet changes, the fallback in the template must follow
+    it.each(PLUGIN_TYPES)('scaffolds %s snippets whose fallback is the parser current text', (type) => {
+      const pluginJson = FULL_PLUGIN_JSON[type];
+      const context = makeContext(pluginJson);
+      docs(context, { docsPath: 'docs' });
+      const values = { pluginName: String(pluginJson.name), pluginId: String(pluginJson.id) };
+      const collapse = (text: string) => text.replace(/\s+/g, ' ').trim();
+      const names: string[] = [];
+
+      for (const page of PAGES_BY_TYPE[type]) {
+        const content = context.getFile(`docs/${page}.md`) ?? '';
+        const { snippets, problems } = readSnippets(content);
+        expect(problems, page).toEqual([]);
+        const lines = content.split('\n');
+        for (const { name, startLine, endLine } of snippets) {
+          names.push(name);
+          expect(collapse(lines.slice(startLine, endLine - 1).join('\n')), `${page} ${name}`).toBe(
+            collapse(renderSnippet(name, values) ?? '')
+          );
+        }
+      }
+
+      expect(names.length).toBeGreaterThan(0);
+    });
+
+    it.each(['datasource', 'app'])('leaves the server logs snippet out of a %s without a backend', (type) => {
+      const context = makeContext({ ...FULL_PLUGIN_JSON[type], backend: false });
+      docs(context, { docsPath: 'docs' });
+      const content = context.getFile('docs/troubleshooting.md') ?? '';
+      expect(content).not.toContain('snippet:server-debug-logs');
+      expect(readSnippets(content)).toEqual({ snippets: [], problems: [] });
+    });
+
     it('interpolates pluginName into the index page', () => {
       const context = makeContext({ type: 'panel', id: 'acme-test-panel', name: 'My Panel' });
       docs(context, { docsPath: 'docs' });

package/src/codemods/additions/scripts/experimental-app-sdk.test.ts

@@ -245,6 +245,62 @@ describe('experimental-app-sdk addition', () => {
     });
   });
 
+  describe('grafana version override', () => {
+    it('adds the image and version build args', () => {
+      const result = appSdk(createAppContext());
+
+      const compose = result.getFile('docker-compose.yaml') ?? '';
+      expect(compose).toContain('grafana_image: ${GRAFANA_IMAGE:-grafana}');
+      expect(compose).toContain('grafana_version: ${GRAFANA_VERSION:-nightly}');
+    });
+
+    it('adds the build args even when the base compose file already enables the toggles', () => {
+      const context = createAppContext();
+      context.addFile(
+        '.config/docker-compose-base.yaml',
+        `services:
+  grafana:
+    environment:
+      GF_FEATURE_TOGGLES_ENABLE: appplugins.loadAppManifest,appplugins.registerAPIServer,grafana.useRouterMiddleware
+`
+      );
+
+      const result = appSdk(context);
+
+      expect(result.getFile('docker-compose.yaml')).toContain('grafana_version: ${GRAFANA_VERSION:-nightly}');
+    });
+
+    it('keeps build args the user already set', () => {
+      const context = createAppContext({
+        compose: `services:
+  grafana:
+    extends:
+      file: .config/docker-compose-base.yaml
+      service: grafana
+    build:
+      args:
+        grafana_version: 12.0.0
+`,
+      });
+
+      const result = appSdk(context);
+
+      const compose = result.getFile('docker-compose.yaml') ?? '';
+      expect(compose).toContain('grafana_version: 12.0.0');
+      expect(compose).not.toContain('GRAFANA_VERSION');
+      expect(compose).toContain('grafana_image: ${GRAFANA_IMAGE:-grafana}');
+    });
+
+    it('is idempotent', () => {
+      const once = appSdk(createAppContext());
+      const compose = once.getFile('docker-compose.yaml');
+
+      const twice = appSdk(once);
+
+      expect(twice.getFile('docker-compose.yaml')).toBe(compose);
+    });
+  });
+
   describe('feature toggle', () => {
     it('enables the app-sdk manifest toggle', () => {
       const context = createAppContext();
@@ -328,7 +384,7 @@ describe('experimental-app-sdk addition', () => {
 
       const result = appSdk(context);
 
-      expect(result.getFile('docker-compose.yaml')).toBe(STOCK_COMPOSE);
+      expect(result.getFile('docker-compose.yaml')).not.toContain('GF_FEATURE_TOGGLES_ENABLE');
     });
 
     it('leaves a list-style environment block alone', () => {
@@ -341,7 +397,8 @@ describe('experimental-app-sdk addition', () => {
 
       const result = appSdk(context);
 
-      expect(result.getFile('docker-compose.yaml')).toBe(listCompose);
+      expect(result.getFile('docker-compose.yaml')).toContain('- GF_FEATURE_TOGGLES_ENABLE=someOtherToggle');
+      expect(result.getFile('docker-compose.yaml')).not.toContain('appplugins.loadAppManifest');
       // The rest of the addition still applies.
       expect(result.doesFileExist('kinds/config.cue')).toBe(true);
     });

package/src/codemods/additions/scripts/experimental-app-sdk.ts

@@ -59,6 +59,7 @@ export default function appSdk(context: Context): Context {
   referenceAgentInstructions(context, data);
   addGenerateScript(context);
   addFeatureToggle(context);
+  addGrafanaVersionOverride(context);
   wireGoBackend(context, data);
 
   // Only guide the user when we actually scaffolded something; a re-run should stay quiet.
@@ -240,6 +241,60 @@ function addFeatureToggle(context: Context) {
   context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
 }
 
+// The app-sdk needs a newer Grafana than the default the plugin was scaffolded with, so the root
+// compose file overrides the build args, while still letting GRAFANA_IMAGE/GRAFANA_VERSION win.
+const GRAFANA_BUILD_ARGS: Record<string, string> = {
+  grafana_image: '${GRAFANA_IMAGE:-grafana}',
+  grafana_version: '${GRAFANA_VERSION:-nightly}',
+};
+
+/**
+ * Overrides the default Grafana image and version in the root docker-compose.yaml. Build args the
+ * user has already set are left alone.
+ */
+function addGrafanaVersionOverride(context: Context) {
+  const composePath = 'docker-compose.yaml';
+  const composeContent = context.getFile(composePath);
+
+  if (!composeContent) {
+    additionsDebug(`Could not find ${composePath}. Skipping the Grafana version override.`);
+    return;
+  }
+
+  const composeData = parseDocument(composeContent);
+
+  if (!(composeData.getIn(['services', 'grafana']) instanceof YAMLMap)) {
+    additionsDebug(`Could not find the grafana service in ${composePath}. Skipping the Grafana version override.`);
+    return;
+  }
+
+  const build = composeData.getIn(['services', 'grafana', 'build']);
+  if (build !== undefined && !(build instanceof YAMLMap)) {
+    additionsDebug(`services.grafana.build in ${composePath} is not a mapping. Skipping the Grafana version override.`);
+    return;
+  }
+
+  const args = composeData.getIn(['services', 'grafana', 'build', 'args']);
+  if (args !== undefined && !(args instanceof YAMLMap)) {
+    additionsDebug(
+      `services.grafana.build.args in ${composePath} is not a mapping. Skipping the Grafana version override.`
+    );
+    return;
+  }
+
+  let changed = false;
+  for (const [name, value] of Object.entries(GRAFANA_BUILD_ARGS)) {
+    if (!composeData.hasIn(['services', 'grafana', 'build', 'args', name])) {
+      composeData.setIn(['services', 'grafana', 'build', 'args', name], value);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    context.updateFile(composePath, stringify(composeData, { lineWidth: 120, singleQuote: true }));
+  }
+}
+
 /**
  * Wires the generated kinds into the Go backend, for app plugins that have one. Go code generation
  * itself is enabled when kinds/config.cue is first scaffolded, in addTemplateFiles.

package/templates/docs/app/docs/AGENTS.md

@@ -108,6 +108,8 @@ To fill a section:
 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.
 
+Text between `<!-- snippet:... -->` and `<!-- /snippet:... -->` markers is maintained by Grafana. Never edit inside it - refer to `snippets.md` in the guides.
+
 ## Validate
 
 ```bash

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

@@ -20,12 +20,16 @@ Before you configure the app, ensure you have:
 
 ## Open the configuration page
 
+<!-- snippet:open-app-config -->
+
 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}}}**.
 
+<!-- /snippet:open-app-config -->
+
 <!-- 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.
 -->

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

@@ -12,6 +12,8 @@ sidebar_position: 6
 
 ## Import a dashboard
 
+<!-- snippet:import-app-dashboard -->
+
 To import a dashboard that ships with {{{pluginName}}}:
 
 1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
@@ -22,6 +24,8 @@ To import a dashboard that ships with {{{pluginName}}}:
 
 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.
 
+<!-- /snippet:import-app-dashboard -->
+
 ## Included dashboards
 
 <!-- section-brief

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

@@ -24,6 +24,8 @@ Fill this in: Keep the list above. Add a bullet in the same **Label:** form for
 
 ## Enable the app
 
+<!-- snippet:enable-app -->
+
 To enable {{{pluginName}}}:
 
 1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
@@ -31,8 +33,10 @@ To enable {{{pluginName}}}:
 1. Select **{{{pluginName}}}**.
 1. Click **Enable**.
 
+<!-- /snippet:enable-app -->
+
 <!-- 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.
+Fill this in: If `src/plugin.json` sets `"autoEnabled": true`, the app is enabled when it's installed, so remove this section, including the steps and their snippet markers. Otherwise keep the steps above and remove only this brief.
 -->
 {{#if hasConfigPage}}
 

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

@@ -32,7 +32,9 @@ Open each H2 with one sentence on when its errors occur. Add an H3 per symptom,
 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:
+<!-- snippet:server-debug-logs -->
+
+In self-managed Grafana, the Grafana server logs show more detail:
 
 1. Set the log level to `debug` in the Grafana configuration file:
 
@@ -44,6 +46,8 @@ In self-managed Grafana, you can also find more detail in the Grafana server log
 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.
+
+<!-- /snippet:server-debug-logs -->
 {{/if}}
 
 ## Get additional help

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

@@ -102,6 +102,8 @@ To fill a section:
 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.
 
+Text between `<!-- snippet:... -->` and `<!-- /snippet:... -->` markers is maintained by Grafana. Never edit inside it - refer to `snippets.md` in the guides.
+
 ## Validate
 
 ```bash

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

@@ -31,6 +31,8 @@ If the reader only needs credentials they already have, remove this section and
 
 ## Add the data source
 
+<!-- snippet:add-data-source -->
+
 To add the {{{pluginName}}} data source:
 
 1. Click **Connections** in the left-side menu.
@@ -39,6 +41,8 @@ To add the {{{pluginName}}} data source:
 1. Select **{{{pluginName}}}**.
 1. Click **Add new data source**.
 
+<!-- /snippet:add-data-source -->
+
 ## Configure settings
 
 <!-- section-brief

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

@@ -12,6 +12,8 @@ sidebar_position: 7
 
 ## Import a dashboard
 
+<!-- snippet:import-dashboard -->
+
 To import a dashboard that ships with {{{pluginName}}}:
 
 1. Click **Connections** > **Data sources** in the left-side menu.
@@ -21,6 +23,8 @@ To import a dashboard that ships with {{{pluginName}}}:
 
 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.
 
+<!-- /snippet:import-dashboard -->
+
 ## Included dashboards
 
 <!-- section-brief

package/templates/docs/datasource/docs/troubleshooting.md

@@ -40,7 +40,9 @@ Open each H2 with one sentence on when its errors occur. Add an H3 per symptom,
 To see the raw request and response for a panel, open the panel editor and click **Query inspector**.
 {{#if hasBackend}}
 
-In self-managed Grafana, you can also find more detail in the Grafana server logs:
+<!-- snippet:server-debug-logs -->
+
+In self-managed Grafana, the Grafana server logs show more detail:
 
 1. Set the log level to `debug` in the Grafana configuration file:
 
@@ -52,6 +54,8 @@ In self-managed Grafana, you can also find more detail in the Grafana server log
 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.
+
+<!-- /snippet:server-debug-logs -->
 {{/if}}
 
 ## Get additional help

package/templates/docs/panel/docs/AGENTS.md

@@ -92,6 +92,8 @@ To fill a section:
 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.
 
+Text between `<!-- snippet:... -->` and `<!-- /snippet:... -->` markers is maintained by Grafana. Never edit inside it - refer to `snippets.md` in the guides.
+
 ## Validate
 
 ```bash

package/templates/docs/panel/docs/data-formats.md

@@ -24,4 +24,8 @@ To see the data the panel receives, open the panel editor, click **Query inspect
 
 ## Reshape data that doesn't match
 
+<!-- snippet:reshape-with-transformations -->
+
 If a query returns data in a different shape, you can reshape it without changing the query. Select the **Transform data** tab in the panel editor and add a transformation. For more information, refer to [Transform data](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/).
+
+<!-- /snippet:reshape-with-transformations -->

package/templates/docs/panel/docs/examples.md

@@ -4,8 +4,12 @@ description: "Worked examples of the {{{yamlEscape pluginName}}} panel."
 sidebar_position: 4
 ---
 
+<!-- snippet:use-example-json -->
+
 To use an example, open your dashboard and go to **Dashboard settings** > **JSON Model**. Paste the excerpt into the `panels` array and click **Save changes**.
 
+<!-- /snippet:use-example-json -->
+
 <!-- section-brief
 Fill this in: Show concrete examples of {{{pluginName}}} configured for real use cases. When the repo has panels of this plugin's type in `provisioning/dashboards/*.json`, take the examples from those before inventing any. Express each example as a `dashboard.json` panel excerpt: `type` and `options`, plus `fieldConfig` and `targets` when the example depends on them. Leave out `id`, `gridPos`, `pluginVersion`, datasource UIDs and timestamps - they are specific to one dashboard and hide the settings that matter. Pair each example with a screenshot of the rendered visualization. Only use a screenshot that the example's JSON produces: open the image and check that what it shows, such as the legend, the values and the number of series, matches the JSON. If no image matches, leave the example without one and flag it. Don't cut settings from an excerpt that its result depends on, such as some of the overrides behind a screenshot.