@grafana/create-plugin 7.15.0 → 7.16.0

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

@@ -125,6 +125,8 @@ interface PageStubs {
   stubs: PageStub[];
   /** Entries in `src/plugin.json` that get no page, as `name (path)`. */
   skipped: string[];
+  /** The file name an app's only page gets, which is still there when the app grows to more pages. */
+  appPageSlug?: string;
 }
 
 interface PageStub {
@@ -218,6 +220,11 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
     // a re-run has no pages to compare against, so it only reports what the first scaffold left out
     skippedPages: hasPages ? [] : pageStubs.skipped,
   };
+  const { appPageSlug } = pageStubs;
+  if (appPageSlug && report.missingPageStubs.length > 0) {
+    // the author may have moved it into features/ or turned it into a folder
+    report.appNamedPage = findPage(context, docsPath, [appPageSlug, `features/${appPageSlug}`]);
+  }
 
   // left alone when it exists, since the author may have customized it
   const workflowPath = '.github/workflows/validate-docs.yml';
@@ -251,13 +258,26 @@ interface PageReport {
   missingPageStubs: string[];
   /** Entries in plugin.json that got no page on the first scaffold, with the reason. */
   skippedPages: string[];
+  /** The page named after the app, when the app has grown past one page and pages are missing. */
+  appNamedPage?: string;
 }
 
 // a page counts as there as a file or as a folder, so authors can turn a page into a folder
 function pageExists(context: Context, docsPath: string, pageNames: string[]): boolean {
-  return pageNames.some(
-    (name) => context.doesFileExist(`${docsPath}/${name}.md`) || context.doesFileExist(`${docsPath}/${name}`)
-  );
+  return findPage(context, docsPath, pageNames) !== undefined;
+}
+
+/** The path of the first page that exists, as `<name>.md` or as the folder `<name>/`. */
+function findPage(context: Context, docsPath: string, pageNames: string[]): string | undefined {
+  for (const name of pageNames) {
+    if (context.doesFileExist(`${docsPath}/${name}.md`)) {
+      return `${docsPath}/${name}.md`;
+    }
+    if (context.doesFileExist(`${docsPath}/${name}`)) {
+      return `${docsPath}/${name}/`;
+    }
+  }
+  return undefined;
 }
 
 /**
@@ -305,7 +325,7 @@ function buildNextStepsMessage(opts: {
   report: PageReport;
 }): ContextMessage {
   const { docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles } = opts;
-  const { missingFeaturePages, missingPageStubs, skippedPages } = opts.report;
+  const { missingFeaturePages, missingPageStubs, skippedPages, appNamedPage } = opts.report;
   const run = (script: string) => output.formatCode(`${packageManagerName} run ${script}`);
 
   const steps: NextStep[] = [
@@ -350,7 +370,9 @@ function buildNextStepsMessage(opts: {
   if (missingPageStubs.length > 0) {
     warnings.push({
       title: `src/plugin.json has pages with no docs page, such as ${missingPageStubs[0]}`,
-      detail: `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted them on purpose, ignore this.`,
+      detail: appNamedPage
+        ? `${appNamedPage} is named after the app, which happens while the app has one page. Rename it after the page it documents, then add pages for the others as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted pages on purpose, ignore this.`
+        : `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted them on purpose, ignore this.`,
     });
   }
   if (skippedPages.length > 0) {
@@ -494,7 +516,11 @@ const TEMPLATE_DEFAULT_PAGES: Record<string, string> = {
 const CONFIG_PAGE_SLUGS = ['configuration', 'configure'];
 
 interface AppFeaturePage {
+  /** The name in plugin.json, which is how the app's own navigation labels the page. */
   name: string;
+  /** What the docs call the page, which is the app's name when it has no other page. */
+  title: string;
+  isOnlyPage?: boolean;
   slug: string;
   path: string;
   role?: string;
@@ -531,7 +557,7 @@ function getAppFeaturePages(
     const role = typeof include.role === 'string' && include.role !== 'Viewer' ? include.role : undefined;
     // an in-app page named like the config page takes its place, the way data sources name it
     if (!hasConfigPage && !configPage && CONFIG_PAGE_SLUGS.includes(slug)) {
-      configPage = { name, slug: 'configure', path, role };
+      configPage = { name, title: name, slug: 'configure', path, role };
       continue;
     }
     if (takenSlugs.has(slug)) {
@@ -540,11 +566,22 @@ function getAppFeaturePages(
       continue;
     }
     takenSlugs.add(slug);
-    pages.push({ name, slug, path, role });
+    pages.push({ name, title: name, slug, path, role });
+  }
+
+  // a single page is the whole app, and its navigation label is often a generic one such as Overview or Home
+  const appSlug = getAppPageSlug(pluginJson);
+  if (pages.length === 1 && appSlug) {
+    pages[0] = { ...pages[0], title: pluginJson.name as string, slug: appSlug, isOnlyPage: true };
   }
   return { pages, configPage, skipped };
 }
 
+function getAppPageSlug(pluginJson: PluginJson): string | undefined {
+  const slug = slugify(pluginJson.name ?? '');
+  return slug && !getReservedPageSlugs().includes(slug) ? slug : undefined;
+}
+
 function slugify(name: string): string {
   return name
     .normalize('NFKD')
@@ -583,6 +620,7 @@ function getAppFeaturePageStubs(pluginJson: PluginJson, featureFlags: Record<str
     });
   }
 
+  const appPageSlug = getAppPageSlug(pluginJson);
   const isInFolder = pages.length > MAX_FLAT_PAGES;
   const folder = isInFolder ? 'features/' : '';
   if (isInFolder) {
@@ -610,6 +648,8 @@ function getAppFeaturePageStubs(pluginJson: PluginJson, featureFlags: Record<str
     },
     stubs,
     skipped,
+    // a page that is already called like the app is the page the author wants, not one to rename
+    appPageSlug: pages.some((page) => page.slug === appPageSlug) ? undefined : appPageSlug,
   };
 }
 

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/src/codemods/migrations/manager.test.ts

@@ -339,5 +339,15 @@ describe('Migrations', () => {
 
       expect(setRootConfig).not.toHaveBeenCalled();
     });
+
+    it('should NOT update version in ".config/.cprc.json" if no migrations made changes', async () => {
+      migrationOneFn.mockImplementation(async (context: Context) => context);
+      migrationTwoFn.mockImplementation(async (context: Context) => context);
+
+      const didMigrationsChangeFiles = await runMigrations(migrations);
+
+      expect(didMigrationsChangeFiles).toBe(false);
+      expect(setRootConfig).not.toHaveBeenCalled();
+    });
   });
 });

package/src/codemods/migrations/manager.ts

@@ -57,21 +57,31 @@ export async function runMigrations(migrations: Migration[], options: RunMigrati
 
   output.log({ title: 'Running the following migrations:', body: migrationListBody });
 
+  let hasAnyChanges = false;
+
   // run migrations sequentially in version order where lowest version runs first
   for (const migration of migrations) {
     const context = await runCodemod(migration, options.codemodOptions);
     const shouldCommit = options.commitEachMigration && context.hasChanges();
 
+    hasAnyChanges ||= context.hasChanges();
+
     if (shouldCommit) {
       // for conventional commits we need to add a newline between the title and the description
       await gitCommitNoVerify(`chore: run create-plugin migration - ${migration.name}\n\n${migration.description}`);
     }
   }
 
+  if (!hasAnyChanges) {
+    return false;
+  }
+
   await setRootConfig({ version: CURRENT_APP_VERSION });
 
   // Nothing to commit when only unreleased migrations re-ran on a plugin already on this version.
   if (options.commitEachMigration && !(await isGitDirectoryClean())) {
     await gitCommitNoVerify(`chore: update .config/.cprc.json to version ${CURRENT_APP_VERSION}.`);
   }
+
+  return true;
 }

package/src/commands/update.command.ts

@@ -43,10 +43,18 @@ export const update = async (argv: minimist.ParsedArgs) => {
 
     // filter out minimist internal properties (_ and $0) before passing to codemod
     const { _, $0, ...codemodOptions } = argv;
-    await runMigrations(migrations, {
+    const didMigrationsChangeFiles = await runMigrations(migrations, {
       commitEachMigration: !!argv.commit,
       codemodOptions,
     });
+
+    if (!didMigrationsChangeFiles) {
+      output.log({
+        title: 'No migrations resulted in changes.',
+      });
+      process.exit(0);
+    }
+
     output.success({
       title: `Successfully updated create-plugin from ${version} to ${CURRENT_APP_VERSION}.`,
     });

package/templates/common/.config/docker-compose-base.yaml

@@ -7,7 +7,7 @@ services:
       context: .
       args:
         grafana_image: ${GRAFANA_IMAGE:-{{~grafanaImage~}} }
-        grafana_version: ${GRAFANA_VERSION:-13.2.3}
+        grafana_version: ${GRAFANA_VERSION:-13.2.4}
         development: ${DEVELOPMENT:-false}
         anonymous_auth_enabled: ${ANONYMOUS_AUTH_ENABLED:-true}
     ports:

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.0",
+    "@grafana/plugin-e2e": "^3.15.1",
     "@grafana/sign-plugin": "^3.3.3",
     "@grafana/tsconfig": "^2.2.0",
     "@playwright/test": "^1.62.1",{{#if useExperimentalRspack}}
@@ -77,11 +77,11 @@
   },
   "dependencies": {
     "@emotion/css": "11.10.6",
-    "@grafana/data": "13.2.3",
-    "@grafana/i18n": "13.2.3",
-    "@grafana/runtime": "13.2.3",
-    "@grafana/ui": "13.2.3",
-    "@grafana/schema": "13.2.3",{{#if_eq pluginType "scenesapp" }}
+    "@grafana/data": "13.2.4",
+    "@grafana/i18n": "13.2.4",
+    "@grafana/runtime": "13.2.4",
+    "@grafana/ui": "13.2.4",
+    "@grafana/schema": "13.2.4",{{#if_eq pluginType "scenesapp" }}
     "@grafana/scenes": "{{ scenesVersion }}",{{/if_eq}}
     "react": "^19.0.0",
     "react-dom": "^19.0.0"{{#if isAppType}},

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

@@ -52,6 +52,8 @@ a `sidebar_position` that puts it where it belongs and link it from `index.md`.
 | An `includes` entry of type `dashboard`                                | `dashboards.md`  | What each bundled dashboard shows and how to import it.                                                                                                                                  |
 | `roles` or `iam` in `src/plugin.json`                                  | `permissions.md` | What each role grants, default assignments and what the app can access.                                                                                                                  |
 
+An app with a single page names that page after the app, because its navigation label is often a generic one such as Overview or Home. Keep that name when you add a second page only if it still describes the page, and otherwise rename the page after what it shows.
+
 When an app page grows too long, turn it into a folder of the same name with an `index.md` and
 split it into pages there. Keep every page within three folder levels of this one.
 
@@ -106,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.
 -->
@@ -38,7 +42,7 @@ Fill this in: An H3 for each section of the config page, named and ordered as th
 | 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.
+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`. When a field's default matches none of the values it offers, such as a different case, give what the page actually does with it. 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.
 -->

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}}
 
@@ -56,7 +60,7 @@ Fill this in: List the jobs someone lands here to do, phrased as tasks rather th
 - [Change the app settings](./configure.md)
 {{/if}}
 {{#if defaultFeaturePage}}
-- [Find your way around {{{defaultFeaturePage.name}}}](./{{defaultFeaturePage.file}}.md)
+- [Find your way around {{{defaultFeaturePage.title}}}](./{{defaultFeaturePage.file}}.md)
 {{/if}}
 {{#if hasDashboards}}
 - [Import the dashboards that ship with the app](./dashboards.md)

package/templates/docs/app/docs/permissions.md

@@ -19,7 +19,7 @@ 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.
+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, based on the role's permissions and the `role` and `action` gates on `includes` entries in `src/plugin.json`, together with any checks in the app's code, not on the role's name. Describe access in terms of pages and actions rather than raw permission names.
 
 If `src/plugin.json` has no `roles`, remove this section and Assign a role below.
 -->

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/app/feature-page.md

@@ -1,14 +1,16 @@
 ---
-title: "{{{yamlEscape page.name}}}"
-description: "Use the {{{yamlEscape page.name}}} page in {{{yamlEscape pluginName}}}."
+title: "{{{yamlEscape page.title}}}"
+description: "{{#if page.isOnlyPage}}Use {{{yamlEscape pluginName}}} in Grafana.{{else}}Use the {{{yamlEscape page.title}}} page in {{{yamlEscape pluginName}}}.{{/if}}"
 keywords:
   - "{{{yamlEscape pluginName}}}"
-  - "{{{yamlEscape page.name}}}"
+{{#unless page.isOnlyPage}}
+  - "{{{yamlEscape page.title}}}"
+{{/unless}}
 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.
+Fill this in: One or two sentences on what {{#if page.isOnlyPage}}{{{pluginName}}} shows{{else}}the {{{page.title}}} page is for{{/if}} and when someone opens it. The app shows it at `{{{page.path}}}`, which its navigation calls {{{page.name}}}. Pair it with a screenshot of the page if `info.screenshots` in `src/plugin.json` has one.
 -->
 {{#if page.role}}
 
@@ -22,5 +24,5 @@ Fill this in: Keep the bullet above. Add a bullet in the same **Label:** form on
 {{/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".
+Fill this in: Replace this brief with one H2 per task someone does {{#if page.isOnlyPage}}in {{{pluginName}}}{{else}}on the {{{page.title}}} page{{/if}}, 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/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

@@ -24,13 +24,15 @@ Fill this in: Keep the list above. Add a bullet in the same **Label:** form for
 ## 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.
+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. Take each permission from what the source calls, not from general knowledge of the service. 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
 
+<!-- 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
@@ -47,7 +51,7 @@ Fill this in: An H3 for each section of the config editor, named and ordered as
 | 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`.
+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`. When a field's default matches none of the values it offers, such as a different case, give what the editor actually does with it.
 
 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.
 

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