@redpanda-data/docs-extensions-and-macros 5.2.5 → 5.3.1

package/tools/rpk-docs/templates/command.hbs

@@ -24,6 +24,11 @@ ifndef::env-cloud[]
 {{/each}}
 
 // tag::single-source[]
+:description: {{{wrapDescriptionPassthrough shortDesc}}}
+{{!-- The description attribute is repeated inside the tagged region so
+     single-sourcing consumers (stub pages that include this tag) inherit
+     the meta description. page-aliases and page-platforms deliberately stay
+     outside the tag: consumers must not inherit alias registrations. --}}
 {{!-- Deprecation notice --}}
 {{#if deprecated}}
 [CAUTION]
@@ -384,8 +389,20 @@ This section provides examples of how to use `{{commandPath}}`.
 |Command |Description
 
 {{#each subcommands}}
+{{#if cloudOnly}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if selfHostedOnly}}
+ifndef::env-cloud[]
+{{/if}}
 |xref:{{xrefPath}}[`{{fullPath}}`]
 |{{{shortDesc}}}
+{{#if cloudOnly}}
+endif::[]
+{{/if}}
+{{#if selfHostedOnly}}
+endif::[]
+{{/if}}
 
 {{/each}}
 |===

package/tools/rpk-docs/templates/content-item.hbs

@@ -2,7 +2,7 @@
 {{~#if (eq type "example")~}}
 {{!-- Single structured example --}}
 {{#if description}}
-{{{description}}}.
+{{{ensurePeriod description}}}
 
 {{/if}}
 [,{{#if language}}{{language}}{{else}}bash{{/if}}{{#if attributes}}{{#each attributes}}{{#if @first}},{{/if}}{{@key}}="{{this}}"{{/each}}{{/if}}]
@@ -27,7 +27,7 @@ This section provides examples of how to use `{{commandPath}}`.
 
 {{#each items}}
 {{#if description}}
-{{{description}}}.
+{{{ensurePeriod description}}}
 
 {{/if}}
 [,{{#if language}}{{language}}{{else}}bash{{/if}}{{#if attributes}}{{#each attributes}}{{#if @first}},{{/if}}{{@key}}="{{this}}"{{/each}}{{/if}}]

package/tools/rpk-docs/validate-overrides.js

@@ -465,8 +465,24 @@ function validatePlatforms(commandOverride, context) {
 function validateFlags(commandOverride, context) {
   const result = new ValidationResult()
 
+  // cloudOnly and selfHostedOnly are mutually exclusive: setting both wraps
+  // the row in an ifdef::env-cloud + ifndef::env-cloud pair that no build
+  // can satisfy, so the row silently vanishes from BOTH sites.
+  if (commandOverride.cloudOnly && commandOverride.selfHostedOnly) {
+    result.addError(
+      'cloudOnly and selfHostedOnly are both set: the command row is unsatisfiable and disappears from every build. Set at most one.',
+      context
+    )
+  }
+
   if (commandOverride.flags) {
     for (const [flagName, flagOverride] of Object.entries(commandOverride.flags)) {
+      if (flagOverride.cloudOnly && flagOverride.selfHostedOnly) {
+        result.addError(
+          `cloudOnly and selfHostedOnly are both set on flag "${flagName}": the flag row is unsatisfiable and disappears from every build. Set at most one.`,
+          `${context}.flags.${flagName}`
+        )
+      }
       // Validate flag name format
       if (!flagName.match(/^[a-zA-Z][-a-zA-Z0-9]*$/)) {
         result.addWarning(