@grafana/create-plugin 7.15.1 → 7.17.0

package/src/codemods/migrations/scripts/019-remove-glob-dependency.test.ts

@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import migrate from './019-remove-glob-dependency.js';
+import { createDefaultContext } from '../../test-utils.js';
+
+const BUNDLER_UTILS_PATH = '.config/bundler/utils.ts';
+const WEBPACK_UTILS_PATH = '.config/webpack/utils.ts';
+
+const CURRENT_UTILS = readFileSync(
+  new URL('../../../../templates/common/.config/bundler/utils.ts', import.meta.url),
+  'utf-8'
+);
+
+const NEW_GLOB_IMPORT = "import { glob } from 'node:fs/promises';";
+const CONSTANTS_IMPORT = "import { SOURCE_DIR } from './constants.ts';";
+
+// The migration appends the new import after the existing ones, so it lands below the constants import.
+const MIGRATED_UTILS = CURRENT_UTILS.replace(`${NEW_GLOB_IMPORT}\n`, '').replace(
+  CONSTANTS_IMPORT,
+  `${CONSTANTS_IMPORT}\n${NEW_GLOB_IMPORT}`
+);
+
+// The template's utils.ts as scaffolded before the glob package was removed.
+const SCAFFOLDED_UTILS = CURRENT_UTILS.replace(
+  "import { glob } from 'node:fs/promises';",
+  "import { glob } from 'glob';"
+).replace(
+  /export async function getEntries\(\) \{[\s\S]*?\n {2}return plugins\.reduce/,
+  `export async function getEntries() {
+  const pluginsJson = await glob('**/src/**/plugin.json', { absolute: true });
+
+  const plugins = await Promise.all(
+    pluginsJson.map((pluginJson) => {
+      const folder = path.dirname(pluginJson);
+      return glob(\`\${folder}/module.{ts,tsx,js,jsx}\`, { absolute: true });
+    })
+  );
+
+  return plugins.reduce`
+);
+
+function createContextWithGlob(utilsPath = BUNDLER_UTILS_PATH, utilsContent = SCAFFOLDED_UTILS) {
+  const context = createDefaultContext();
+  context.addFile(utilsPath, utilsContent);
+  context.updateFile(
+    'package.json',
+    JSON.stringify({ devDependencies: { '@grafana/tsconfig': '^2.0.1', glob: '^11.1.0' } }, null, 2)
+  );
+
+  return context;
+}
+
+function getDevDependencies(context: ReturnType<typeof createDefaultContext>) {
+  return JSON.parse(context.getFile('package.json') ?? '{}').devDependencies;
+}
+
+describe('Migration - remove glob dependency', () => {
+  it('should be idempotent', async () => {
+    const context = createContextWithGlob();
+
+    await expect(migrate).toBeIdempotent(context);
+  });
+
+  it('should migrate the scaffolded utils to the current template', () => {
+    const context = migrate(createContextWithGlob());
+
+    expect(context.getFile(BUNDLER_UTILS_PATH)).toBe(MIGRATED_UTILS);
+  });
+
+  it('should migrate the legacy webpack utils location', () => {
+    const context = migrate(createContextWithGlob(WEBPACK_UTILS_PATH));
+
+    expect(context.getFile(WEBPACK_UTILS_PATH)).toBe(MIGRATED_UTILS);
+  });
+
+  it('should remove glob from package.json', () => {
+    const context = migrate(createContextWithGlob());
+
+    expect(getDevDependencies(context)).toEqual({ '@grafana/tsconfig': '^2.0.1' });
+  });
+
+  it('should migrate a customised getEntries that calls glob', () => {
+    const customisedUtils = SCAFFOLDED_UTILS.replace(
+      '{ absolute: true });\n\n  const plugins',
+      "{ absolute: true, ignore: ['node_modules/**'] });\n\n  const plugins"
+    );
+    const context = migrate(createContextWithGlob(BUNDLER_UTILS_PATH, customisedUtils));
+
+    expect(context.getFile(BUNDLER_UTILS_PATH)).toBe(MIGRATED_UTILS);
+  });
+
+  it('should skip a getEntries that does not call glob', () => {
+    const noGlobCallUtils = SCAFFOLDED_UTILS.replace(
+      "const pluginsJson = await glob('**/src/**/plugin.json', { absolute: true });",
+      "const pluginsJson = ['src/plugin.json'];"
+    ).replace('return glob(', 'return Promise.resolve(');
+    const context = createContextWithGlob(BUNDLER_UTILS_PATH, noGlobCallUtils);
+
+    migrate(context);
+
+    expect(context.getFile(BUNDLER_UTILS_PATH)).toBe(noGlobCallUtils);
+    expect(getDevDependencies(context).glob).toBe('^11.1.0');
+  });
+
+  it('should skip an aliased glob import', () => {
+    const aliasedUtils = SCAFFOLDED_UTILS.replace("import { glob } from 'glob';", "import { glob as g } from 'glob';")
+      .replaceAll('await glob(', 'await g(')
+      .replace('return glob(', 'return g(');
+    const context = createContextWithGlob(BUNDLER_UTILS_PATH, aliasedUtils);
+
+    migrate(context);
+
+    expect(context.getFile(BUNDLER_UTILS_PATH)).toBe(aliasedUtils);
+    expect(getDevDependencies(context).glob).toBe('^11.1.0');
+  });
+
+  it('should keep other glob specifiers and the dependency', () => {
+    const mixedUtils = SCAFFOLDED_UTILS.replace(
+      "import { glob } from 'glob';",
+      "import { glob, globSync } from 'glob';"
+    );
+    const context = migrate(createContextWithGlob(BUNDLER_UTILS_PATH, mixedUtils));
+    const migrated = context.getFile(BUNDLER_UTILS_PATH);
+
+    expect(migrated).toContain("import { globSync } from 'glob';");
+    expect(migrated).toContain("import { glob } from 'node:fs/promises';");
+    expect(migrated).toContain("for await (const pluginJson of glob('**/src/**/plugin.json'))");
+    expect(getDevDependencies(context).glob).toBe('^11.1.0');
+  });
+
+  it('should leave files without a glob import unchanged', () => {
+    const context = createContextWithGlob(BUNDLER_UTILS_PATH, CURRENT_UTILS);
+
+    migrate(context);
+
+    expect(context.getFile(BUNDLER_UTILS_PATH)).toBe(CURRENT_UTILS);
+    expect(getDevDependencies(context).glob).toBe('^11.1.0');
+  });
+
+  it('should not fail when the utils file cannot be parsed', () => {
+    const context = createContextWithGlob(BUNDLER_UTILS_PATH, "import { glob } from 'glob';\nexport function {");
+
+    expect(() => migrate(context)).not.toThrow();
+    expect(getDevDependencies(context).glob).toBe('^11.1.0');
+  });
+});

package/src/codemods/migrations/scripts/019-remove-glob-dependency.ts

@@ -0,0 +1,121 @@
+import type { Context } from '../../context.js';
+import * as recast from 'recast';
+import {
+  callsFunction,
+  createImport,
+  findImports,
+  findFunctionDeclaration,
+  findNamedImport,
+  insertImports,
+  parseAsTypescript,
+  printAST,
+} from '../../utils.ast.js';
+import { migrationsDebug, removeDependenciesFromPackageJson } from '../../utils.js';
+
+const OLD_PACKAGE_NAME = 'glob';
+const NEW_PACKAGE_NAME = 'node:fs/promises';
+
+const UTILS_PATHS = ['.config/webpack/utils.ts', '.config/bundler/utils.ts'];
+
+const GET_ENTRIES_SOURCE = `export async function getEntries() {
+  const plugins: string[][] = [];
+  for await (const pluginJson of glob('**/src/**/plugin.json')) {
+    const folder = path.dirname(pluginJson);
+    const modules: string[] = [];
+    for await (const module of glob(\`\${folder}/module.{ts,tsx,js,jsx}\`)) {
+      modules.push(path.resolve(module));
+    }
+    plugins.push(modules);
+  }
+
+  return plugins.reduce<Record<string, string>>((result, modules) => {
+    return modules.reduce((innerResult, module) => {
+      const pluginPath = path.dirname(module);
+      const pluginName = path.relative(process.cwd(), pluginPath).replace(/src\\/?/i, '');
+      const entryName = pluginName === '' ? 'module' : \`\${pluginName}/module\`;
+
+      innerResult[entryName] = module;
+      return innerResult;
+    }, result);
+  }, {});
+}`;
+
+export default function migrate(context: Context) {
+  const updatedPaths = UTILS_PATHS.filter((filePath) => replaceGlobWithFsGlob(context, filePath));
+  if (updatedPaths.length === 0) {
+    return context;
+  }
+
+  const isStillUsed = UTILS_PATHS.some((filePath) => {
+    const source = context.getFile(filePath);
+    if (!source) {
+      return false;
+    }
+    const parsed = parseAsTypescript(source);
+    return !parsed.success || findImports(parsed.ast, OLD_PACKAGE_NAME).length > 0;
+  });
+
+  if (context.doesFileExist('package.json') && !isStillUsed) {
+    removeDependenciesFromPackageJson(context, [OLD_PACKAGE_NAME], [OLD_PACKAGE_NAME]);
+  }
+
+  return context;
+}
+
+function replaceGlobWithFsGlob(context: Context, utilsPath: string): boolean {
+  if (!context.doesFileExist(utilsPath)) {
+    return false;
+  }
+
+  const source = context.getFile(utilsPath);
+  if (!source || !source.includes(OLD_PACKAGE_NAME)) {
+    return false;
+  }
+
+  const parsed = parseAsTypescript(source);
+  if (!parsed.success) {
+    migrationsDebug(`Failed to parse ${utilsPath}. Error: ${parsed.error.message}`);
+    return false;
+  }
+
+  const globImport = findNamedImport(parsed.ast, OLD_PACKAGE_NAME, 'glob');
+  if (!globImport) {
+    return false;
+  }
+
+  const getEntries = findFunctionDeclaration(parsed.ast, 'getEntries');
+  if (!getEntries) {
+    return false;
+  }
+
+  // The new body calls glob directly, so an aliased import (and its calls) is left alone.
+  if (!callsFunction(getEntries.body, 'glob')) {
+    return false;
+  }
+
+  const { declaration, specifier } = globImport;
+  declaration.specifiers = (declaration.specifiers ?? []).filter((candidate) => candidate !== specifier);
+  if (declaration.specifiers.length === 0) {
+    parsed.ast.program.body.splice(parsed.ast.program.body.indexOf(declaration), 1);
+  }
+  insertImports(parsed.ast, [createImport({ named: [{ name: 'glob' }] }, NEW_PACKAGE_NAME)]);
+
+  getEntries.body = getFunctionBody(GET_ENTRIES_SOURCE);
+
+  context.updateFile(utilsPath, printAST(parsed.ast));
+  return true;
+}
+
+function getFunctionBody(source: string): recast.types.namedTypes.BlockStatement {
+  const parsed = parseAsTypescript(source);
+  if (!parsed.success) {
+    throw parsed.error;
+  }
+
+  const [statement] = parsed.ast.program.body;
+  if (statement?.type !== 'ExportNamedDeclaration' || statement.declaration?.type !== 'FunctionDeclaration') {
+    throw new Error('Failed to parse target function body');
+  }
+
+  return statement.declaration.body;
+}

package/src/codemods/utils.ast.test.ts

@@ -7,6 +7,10 @@ import {
   findObjectProperty,
   createImport,
   insertImports,
+  findImports,
+  findNamedImport,
+  findFunctionDeclaration,
+  callsFunction,
 } from './utils.ast.js';
 
 // Helper to create a simple test AST from source code
@@ -31,6 +35,58 @@ function findFirstNode<T extends recast.types.namedTypes.Node>(ast: recast.types
 }
 
 describe('utils.ast', () => {
+  describe('Declaration Utilities', () => {
+    describe('findFunctionDeclaration', () => {
+      it('should find a function declaration by name', () => {
+        const ast = createTestAST(`function foo() {}\nfunction bar() {}`);
+
+        const declaration = findFunctionDeclaration(ast, 'bar');
+
+        expect(declaration?.id?.name).toBe('bar');
+      });
+
+      it('should find an exported function declaration', () => {
+        const ast = createTestAST(`export async function getEntries() {}`);
+
+        const declaration = findFunctionDeclaration(ast, 'getEntries');
+
+        expect(declaration?.async).toBe(true);
+      });
+
+      it('should return null when the function is not declared', () => {
+        const ast = createTestAST(`const getEntries = () => {};`);
+
+        expect(findFunctionDeclaration(ast, 'getEntries')).toBeNull();
+      });
+    });
+
+    describe('callsFunction', () => {
+      it('should return true when the function is called', () => {
+        const ast = createTestAST(`async function run() { const files = await glob('**/*.ts'); }`);
+
+        expect(callsFunction(ast, 'glob')).toBe(true);
+      });
+
+      it('should return true for nested calls', () => {
+        const ast = createTestAST(`items.map((item) => wrap(glob(item)));`);
+
+        expect(callsFunction(ast, 'glob')).toBe(true);
+      });
+
+      it('should return false when the function is only referenced', () => {
+        const ast = createTestAST(`const fn = glob;`);
+
+        expect(callsFunction(ast, 'glob')).toBe(false);
+      });
+
+      it('should return false for a method with the same name', () => {
+        const ast = createTestAST(`fs.glob('**/*.ts');`);
+
+        expect(callsFunction(ast, 'glob')).toBe(false);
+      });
+    });
+  });
+
   describe('Property Utilities', () => {
     describe('isProperty', () => {
       it('should return true for Property nodes', () => {
@@ -191,5 +247,100 @@ describe('utils.ast', () => {
         expect(output).toBe(`import React from 'react';\nimport { map } from 'lodash';\nconst x = 1;`);
       });
     });
+
+    describe('findImports', () => {
+      it('should return an empty array when the package is not imported', () => {
+        const ast = createTestAST(`import React from 'react';\nconst x = 1;`);
+
+        expect(findImports(ast, 'glob')).toEqual([]);
+      });
+
+      it('should return the matching import declaration', () => {
+        const ast = createTestAST(`import React from 'react';\nimport { glob } from 'glob';`);
+
+        const imports = findImports(ast, 'glob');
+
+        expect(imports).toHaveLength(1);
+        expect(imports[0].source.value).toBe('glob');
+      });
+
+      it('should return every declaration importing the package', () => {
+        const ast = createTestAST(`import { glob } from 'glob';\nimport type { GlobOptions } from 'glob';`);
+
+        expect(findImports(ast, 'glob')).toHaveLength(2);
+      });
+
+      it('should not match packages with a similar name', () => {
+        const ast = createTestAST(`import globParent from 'glob-parent';\nimport { glob } from 'node:fs/promises';`);
+
+        expect(findImports(ast, 'glob')).toEqual([]);
+      });
+    });
+
+    describe('findNamedImport', () => {
+      it('should find a named import', () => {
+        const ast = createTestAST(`import { glob } from 'glob';`);
+
+        const match = findNamedImport(ast, 'glob', 'glob');
+
+        expect(match).toBeDefined();
+        expect(match?.declaration.source.value).toBe('glob');
+        expect(match?.specifier.imported.name).toBe('glob');
+        expect(match?.specifier.local?.name).toBe('glob');
+      });
+
+      it('should find an aliased named import by its imported name', () => {
+        const ast = createTestAST(`import { glob as g } from 'glob';`);
+
+        const match = findNamedImport(ast, 'glob', 'glob');
+
+        expect(match).toBeDefined();
+        expect(match?.specifier.local?.name).toBe('g');
+      });
+
+      it('should find the specifier among other specifiers', () => {
+        const ast = createTestAST(`import { globSync, glob } from 'glob';`);
+
+        const match = findNamedImport(ast, 'glob', 'glob');
+
+        expect(match).toBeDefined();
+        expect(match?.declaration.specifiers).toHaveLength(2);
+        expect(match?.specifier.imported.name).toBe('glob');
+      });
+
+      it('should find the specifier in a later declaration of the same package', () => {
+        const ast = createTestAST(`import type { GlobOptions } from 'glob';\nimport { glob } from 'glob';`);
+        const [, secondDeclaration] = findImports(ast, 'glob');
+
+        const match = findNamedImport(ast, 'glob', 'glob');
+
+        expect(match).toBeDefined();
+        expect(match?.declaration).toBe(secondDeclaration);
+      });
+
+      it('should return undefined when only other named imports exist', () => {
+        const ast = createTestAST(`import { globSync } from 'glob';`);
+
+        expect(findNamedImport(ast, 'glob', 'glob')).toBeUndefined();
+      });
+
+      it('should return undefined for a default import', () => {
+        const ast = createTestAST(`import glob from 'glob';`);
+
+        expect(findNamedImport(ast, 'glob', 'glob')).toBeUndefined();
+      });
+
+      it('should return undefined for a namespace import', () => {
+        const ast = createTestAST(`import * as glob from 'glob';`);
+
+        expect(findNamedImport(ast, 'glob', 'glob')).toBeUndefined();
+      });
+
+      it('should return undefined when the package is not imported', () => {
+        const ast = createTestAST(`import { glob } from 'node:fs/promises';`);
+
+        expect(findNamedImport(ast, 'glob', 'glob')).toBeUndefined();
+      });
+    });
   });
 });

package/src/codemods/utils.ast.ts

@@ -45,6 +45,42 @@ export function findVariableDeclaration(
   return found;
 }
 
+export function findFunctionDeclaration(
+  ast: recast.types.ASTNode,
+  functionName: string
+): recast.types.namedTypes.FunctionDeclaration | null {
+  let found = null;
+
+  recast.types.visit(ast, {
+    visitFunctionDeclaration(path) {
+      if (path.node.id?.name === functionName) {
+        found = path.node;
+        return false; // Stop traversal
+      }
+      return this.traverse(path);
+    },
+  });
+
+  return found;
+}
+
+export function callsFunction(ast: recast.types.ASTNode, functionName: string): boolean {
+  let isCalled = false;
+
+  recast.types.visit(ast, {
+    visitCallExpression(path) {
+      const { callee } = path.node;
+      if (callee.type === 'Identifier' && callee.name === functionName) {
+        isCalled = true;
+        return false; // Stop traversal
+      }
+      return this.traverse(path);
+    },
+  });
+
+  return isCalled;
+}
+
 export function isProperty(
   node: recast.types.ASTNode
 ): node is recast.types.namedTypes.Property | recast.types.namedTypes.ObjectProperty {
@@ -108,3 +144,27 @@ export function insertImports(
     ast.program.body.unshift(...imports);
   }
 }
+
+export function findImports(
+  ast: recast.types.namedTypes.File,
+  packageName: string
+): recast.types.namedTypes.ImportDeclaration[] {
+  return ast.program.body.filter(
+    (node): node is recast.types.namedTypes.ImportDeclaration =>
+      node.type === 'ImportDeclaration' && node.source.value === packageName
+  );
+}
+
+export function findNamedImport(ast: recast.types.namedTypes.File, packageName: string, importedName: string) {
+  for (const declaration of findImports(ast, packageName)) {
+    const specifier = declaration.specifiers?.find(
+      (candidate): candidate is recast.types.namedTypes.ImportSpecifier =>
+        candidate.type === 'ImportSpecifier' && candidate.imported.name === importedName
+    );
+    if (specifier) {
+      return { declaration, specifier };
+    }
+  }
+
+  return undefined;
+}

package/templates/common/.config/bundler/utils.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import process from 'process';
 import os from 'os';
 import path from 'path';
-import { glob } from 'glob';
+import { glob } from 'node:fs/promises';
 import { SOURCE_DIR } from './constants.ts';
 
 export function isWSL() {
@@ -46,14 +46,15 @@ export function hasReadme() {
 // Support bundling nested plugins by finding all plugin.json files in src directory
 // then checking for a sibling module.[jt]sx? file.
 export async function getEntries() {
-  const pluginsJson = await glob('**/src/**/plugin.json', { absolute: true });
-
-  const plugins = await Promise.all(
-    pluginsJson.map((pluginJson) => {
-      const folder = path.dirname(pluginJson);
-      return glob(`${folder}/module.{ts,tsx,js,jsx}`, { absolute: true });
-    })
-  );
+  const plugins: string[][] = [];
+  for await (const pluginJson of glob('**/src/**/plugin.json')) {
+    const folder = path.dirname(pluginJson);
+    const modules: string[] = [];
+    for await (const module of glob(`${folder}/module.{ts,tsx,js,jsx}`)) {
+      modules.push(path.resolve(module));
+    }
+    plugins.push(modules);
+  }
 
   return plugins.reduce<Record<string, string>>((result, modules) => {
     return modules.reduce((innerResult, module) => {

package/templates/common/_package.json

@@ -17,7 +17,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@grafana/eslint-config": "^10.0.0",
-    "@grafana/plugin-e2e": "^3.15.1",
+    "@grafana/plugin-e2e": "^3.15.2",
     "@grafana/sign-plugin": "^3.3.3",
     "@grafana/tsconfig": "^2.2.0",
     "@playwright/test": "^1.62.1",{{#if useExperimentalRspack}}
@@ -46,7 +46,6 @@
     "eslint-plugin-react-hooks": "^7.1.0",{{#if useExperimentalRspack}}
     "eslint-webpack-plugin": "^5.0.0",{{/if}}{{#unless useExperimentalRspack}}
     "fork-ts-checker-webpack-plugin": "^9.1.0",{{/unless}}
-    "glob": "^11.1.0",
     "identity-obj-proxy": "^3.0.0",
     "imports-loader": "^5.0.0",
     "intersection-observer": "^0.12.2",

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