@redpanda-data/docs-extensions-and-macros 5.0.3 → 5.1.0

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

@@ -0,0 +1,576 @@
+{{!-- Cloud-only wrapper start --}}
+{{#if cloudOnly}}
+ifdef::env-cloud[]
+{{/if}}
+{{!-- Self-hosted-only wrapper start --}}
+{{#if selfHostedOnly}}
+ifndef::env-cloud[]
+{{/if}}
+= {{commandPath}}
+:description: {{{wrapDescriptionPassthrough shortDesc}}}
+{{#if pageAliases}}
+:page-aliases: {{{pageAliases}}}
+{{/if}}
+{{#if pagePlatforms}}
+:page-platforms: {{pagePlatforms}}
+{{/if}}
+{{#if deprecated}}
+:page-deprecated: true
+{{/if}}
+
+// This content is autogenerated. Do not edit manually. To customize content, see the writer's guide: https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/docs-data/RPK_OVERRIDES_GUIDE.adoc
+{{#each pageAttributes}}
+:{{@key}}: {{this}}
+{{/each}}
+
+// tag::single-source[]
+{{!-- Deprecation notice --}}
+{{#if deprecated}}
+[CAUTION]
+====
+This command is deprecated{{#if deprecatedInVersion}} as of {{deprecatedInVersion}}{{/if}}{{#if removedInVersion}} and will be removed in {{removedInVersion}}{{/if}}.{{#if replacement}} {{{replacement}}}{{/if}}{{#if deprecatedMessage}} {{{deprecatedMessage}}}{{/if}}
+====
+
+{{/if}}
+{{!-- Admonitions after header --}}
+{{#if admonitions.afterHeader}}
+{{{admonitions.afterHeader}}}
+
+{{/if}}
+{{!-- Cloud-only content after header --}}
+{{#if cloudContent.afterHeader}}
+ifdef::env-cloud[]
+{{{cloudContent.afterHeader}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after header --}}
+{{#if selfHostedContent.afterHeader}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterHeader}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after header --}}
+{{#each includes.afterHeader}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after header --}}
+{{#each customSectionsByPosition.after_header}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{#if (eq descriptionScope "self-hosted")}}
+ifndef::env-cloud[]
+{{{description}}}
+endif::[]
+{{else if (eq descriptionScope "cloud-only")}}
+ifdef::env-cloud[]
+{{{description}}}
+endif::[]
+{{else}}
+{{{description}}}
+{{/if}}
+
+{{#if isLinuxOnly}}
+NOTE: This command is only available on Linux.
+
+{{/if}}
+{{#if isDarwinOnly}}
+NOTE: This command is only available on macOS.
+
+{{/if}}
+{{#if introducedInVersion}}
+NOTE: This command was introduced in{{#if pluginName}} {{pluginName}}{{/if}} version {{introducedInVersion}}.
+
+{{/if}}
+{{#if minVersion}}
+NOTE: This command requires rpk version {{minVersion}} or later.
+
+{{/if}}
+{{!-- Admonitions after description --}}
+{{#if admonitions.afterDescription}}
+{{{admonitions.afterDescription}}}
+
+{{/if}}
+{{!-- Cloud-only content after description --}}
+{{#if cloudContent.afterDescription}}
+ifdef::env-cloud[]
+{{{cloudContent.afterDescription}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after description --}}
+{{#if selfHostedContent.afterDescription}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterDescription}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after description --}}
+{{#each includes.afterDescription}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after description --}}
+{{#each customSectionsByPosition.after_description}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{!-- Prerequisites section --}}
+{{#if hasPrerequisites}}
+== Prerequisites
+
+{{#each prerequisites}}
+* {{{this}}}
+{{/each}}
+
+{{/if}}
+{{#if usage}}
+== Usage
+
+[,bash]
+----
+{{{usage}}}
+----
+{{/if}}
+
+{{!-- Admonitions after usage --}}
+{{#if admonitions.afterUsage}}
+{{{admonitions.afterUsage}}}
+
+{{/if}}
+{{!-- Cloud-only content after usage --}}
+{{#if cloudContent.afterUsage}}
+ifdef::env-cloud[]
+{{{cloudContent.afterUsage}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after usage --}}
+{{#if selfHostedContent.afterUsage}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterUsage}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after usage --}}
+{{#each includes.afterUsage}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after usage --}}
+{{#each customSectionsByPosition.after_usage}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+
+{{!-- All sections from rpk source appear as subsections (===) under Usage --}}
+{{#if (lookup sections "COMMON FILES")}}
+=== Common files
+
+{{{lookup sections "COMMON FILES"}}}
+
+{{/if}}
+{{#if (lookup sections "BARE-METAL")}}
+=== Bare-metal
+
+{{{lookup sections "BARE-METAL"}}}
+
+{{/if}}
+{{#if sections.KUBERNETES}}
+=== Kubernetes
+
+{{{sections.KUBERNETES}}}
+
+{{/if}}
+{{#if (lookup sections "EXTRA REQUESTS FOR PARTITIONS")}}
+=== Extra requests for partitions
+
+{{{lookup sections "EXTRA REQUESTS FOR PARTITIONS"}}}
+
+{{/if}}
+{{#if sections.FORMAT}}
+=== Format
+
+{{{sections.FORMAT}}}
+
+{{/if}}
+{{#if sections.COLORS}}
+=== Colors
+
+{{{sections.COLORS}}}
+
+{{/if}}
+{{#if sections.MODIFIERS}}
+=== Modifiers
+
+{{{sections.MODIFIERS}}}
+
+{{/if}}
+{{#if (lookup sections "RAW MODE")}}
+=== Raw mode
+
+{{{lookup sections "RAW MODE"}}}
+
+{{/if}}
+{{#if sections.PRINCIPALS}}
+=== Principals
+
+{{{sections.PRINCIPALS}}}
+
+{{/if}}
+{{#if sections.ROLES}}
+=== Roles
+
+{{{sections.ROLES}}}
+
+{{/if}}
+{{#if sections.HOSTS}}
+=== Hosts
+
+{{{sections.HOSTS}}}
+
+{{/if}}
+{{#if sections.RESOURCES}}
+=== Resources
+
+{{{sections.RESOURCES}}}
+
+{{/if}}
+{{#if sections.OPERATIONS}}
+=== Operations
+
+{{{sections.OPERATIONS}}}
+
+{{/if}}
+{{#if sections.PERMISSIONS}}
+=== Permissions
+
+{{{sections.PERMISSIONS}}}
+
+{{/if}}
+{{#if sections.MANAGEMENT}}
+=== Management
+
+{{{sections.MANAGEMENT}}}
+
+{{/if}}
+{{#if sections.NUMBERS}}
+=== Numbers
+
+{{{sections.NUMBERS}}}
+
+{{/if}}
+{{#if sections.TEXT}}
+=== Text
+
+{{{sections.TEXT}}}
+
+{{/if}}
+{{#if sections.HEADERS}}
+=== Headers
+
+{{{sections.HEADERS}}}
+
+{{/if}}
+{{#if sections.ATTRIBUTES}}
+=== Attributes
+
+{{{sections.ATTRIBUTES}}}
+
+{{/if}}
+{{#if sections.OFFSETS}}
+=== Offsets
+
+{{{sections.OFFSETS}}}
+
+{{/if}}
+{{#if sections.VALUES}}
+=== Values
+
+{{{sections.VALUES}}}
+
+{{/if}}
+{{#if (lookup sections "SCHEMA-REGISTRY")}}
+=== Schema registry
+
+{{{lookup sections "SCHEMA-REGISTRY"}}}
+
+{{/if}}
+{{#if sections.TOMBSTONES}}
+=== Tombstones
+
+{{{sections.TOMBSTONES}}}
+
+{{/if}}
+{{!-- Unknown sections also as subsections --}}
+{{#if hasUnknownSections}}
+{{#each unknownSections}}
+=== {{{sectionTitle name}}}
+
+{{{content}}}
+
+{{/each}}
+{{/if}}
+{{#if sections.MISC}}
+=== Miscellaneous
+
+{{{sections.MISC}}}
+
+{{/if}}
+{{#if sections.NOTES}}
+=== Notes
+
+{{{sections.NOTES}}}
+{{/if}}
+
+{{#if aliases.length}}
+== Aliases
+
+[,bash]
+----
+{{#each aliases}}
+{{this}}
+{{/each}}
+----
+{{#if aliasNotes}}
+
+NOTE: {{{aliasNotes}}}
+{{/if}}
+{{/if}}
+
+{{!-- Admonitions after aliases --}}
+{{#if admonitions.afterAliases}}
+{{{admonitions.afterAliases}}}
+
+{{/if}}
+{{!-- Cloud-only content after aliases --}}
+{{#if cloudContent.afterAliases}}
+ifdef::env-cloud[]
+{{{cloudContent.afterAliases}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after aliases --}}
+{{#if selfHostedContent.afterAliases}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterAliases}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after aliases --}}
+{{#each includes.afterAliases}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after aliases --}}
+{{#each customSectionsByPosition.after_aliases}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{!-- Examples section at level 2, after aliases --}}
+{{#if sections.EXAMPLES}}
+== Examples
+
+This section provides examples of how to use `{{commandPath}}`.
+
+{{{sections.EXAMPLES}}}
+
+{{/if}}
+{{!-- Subcommands table - before flags --}}
+{{#if hasSubcommands}}
+== Subcommands
+
+[cols="1,2a"]
+|===
+|Command |Description
+
+{{#each subcommands}}
+|xref:{{xrefPath}}[`{{fullPath}}`]
+|{{{shortDesc}}}
+
+{{/each}}
+|===
+
+{{/if}}
+{{#if flags.length}}
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|Value |Type |Description
+
+{{#each flags}}
+{{#if cloudOnly}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if selfHostedOnly}}
+ifndef::env-cloud[]
+{{/if}}
+|{{name}} |{{type}} |{{#if deprecated}}*[Deprecated{{#if deprecatedMessage}}: {{deprecatedMessage}}{{/if}}]* {{/if}}{{{escapePipes description}}}{{#if validValues}} Valid values: {{#each validValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}.{{/if}}{{#if introducedInVersion}} _(New in {{introducedInVersion}})_{{/if}}
+{{#if cloudOnly}}
+endif::[]
+{{/if}}
+{{#if selfHostedOnly}}
+endif::[]
+{{/if}}
+{{/each}}
+|===
+{{/if}}
+
+{{#if globalFlags.length}}
+== Global flags
+
+[cols="1m,1a,2a"]
+|===
+|Value |Type |Description
+
+{{#each globalFlags}}
+|{{#if shorthand}}-{{shorthand}}, {{/if}}--{{name}} |{{type}} |{{{escapePipes description}}}
+{{/each}}
+|===
+{{/if}}
+
+{{!-- Admonitions after flags --}}
+{{#if admonitions.afterFlags}}
+{{{admonitions.afterFlags}}}
+
+{{/if}}
+{{!-- Cloud-only content after flags --}}
+{{#if cloudContent.afterFlags}}
+ifdef::env-cloud[]
+{{{cloudContent.afterFlags}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after flags --}}
+{{#if selfHostedContent.afterFlags}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterFlags}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after flags --}}
+{{#each includes.afterFlags}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after flags --}}
+{{#each customSectionsByPosition.after_flags}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{!-- Admonitions after examples --}}
+{{#if admonitions.afterExamples}}
+{{{admonitions.afterExamples}}}
+
+{{/if}}
+{{!-- Cloud-only content after examples --}}
+{{#if cloudContent.afterExamples}}
+ifdef::env-cloud[]
+{{{cloudContent.afterExamples}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content after examples --}}
+{{#if selfHostedContent.afterExamples}}
+ifndef::env-cloud[]
+{{{selfHostedContent.afterExamples}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes after examples --}}
+{{#each includes.afterExamples}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned after examples --}}
+{{#each customSectionsByPosition.after_examples}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{!-- Admonitions before see also --}}
+{{#if admonitions.beforeSeeAlso}}
+{{{admonitions.beforeSeeAlso}}}
+
+{{/if}}
+{{!-- Cloud-only content before see also --}}
+{{#if cloudContent.beforeSeeAlso}}
+ifdef::env-cloud[]
+{{{cloudContent.beforeSeeAlso}}}
+endif::[]
+
+{{/if}}
+{{!-- Self-hosted content before see also --}}
+{{#if selfHostedContent.beforeSeeAlso}}
+ifndef::env-cloud[]
+{{{selfHostedContent.beforeSeeAlso}}}
+endif::[]
+
+{{/if}}
+{{!-- Includes before see also --}}
+{{#each includes.beforeSeeAlso}}
+include::{{{this}}}[]
+
+{{/each}}
+{{!-- Custom sections positioned before see also --}}
+{{#each customSectionsByPosition.before_see_also}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+{{!-- Suggested reading section for additional links --}}
+{{#if hasSeeAlso}}
+
+== Suggested reading
+
+{{#each seeAlso}}
+{{#if (isObject this)}}
+{{#if cloudOnly}}
+ifdef::env-cloud[]
+* {{{content}}}
+endif::[]
+{{else if selfHostedOnly}}
+ifndef::env-cloud[]
+* {{{content}}}
+endif::[]
+{{else}}
+* {{{content}}}
+{{/if}}
+{{else}}
+* {{{this}}}
+{{/if}}
+{{/each}}
+
+{{/if}}
+{{!-- Admonitions at end --}}
+{{#if admonitions.end}}
+
+{{{admonitions.end}}}
+{{/if}}
+{{!-- Cloud-only content at end --}}
+{{#if cloudContent.end}}
+
+ifdef::env-cloud[]
+{{{cloudContent.end}}}
+endif::[]
+{{/if}}
+{{!-- Self-hosted content at end --}}
+{{#if selfHostedContent.end}}
+
+ifndef::env-cloud[]
+{{{selfHostedContent.end}}}
+endif::[]
+{{/if}}
+{{!-- Includes at end --}}
+{{#each includes.end}}
+
+include::{{{this}}}[]
+{{/each}}
+{{!-- Custom sections positioned at end --}}
+{{#each customSectionsByPosition.end}}
+{{> content-item this commandPath=../commandPath}}
+{{/each}}
+// end::single-source[]
+{{!-- Self-hosted-only wrapper end --}}
+{{#if selfHostedOnly}}
+endif::[]
+{{/if}}
+{{!-- Cloud-only wrapper end --}}
+{{#if cloudOnly}}
+endif::[]
+{{/if}}

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

@@ -0,0 +1,106 @@
+{{!-- Render a content item based on its type --}}
+{{~#if (eq type "example")~}}
+{{!-- Single structured example --}}
+{{#if description}}
+{{{description}}}.
+
+{{/if}}
+[,{{#if language}}{{language}}{{else}}bash{{/if}}{{#if attributes}}{{#each attributes}}{{#if @first}},{{/if}}{{@key}}="{{this}}"{{/each}}{{/if}}]
+----
+{{{code}}}
+----
+{{#if output}}
+
+Output:
+
+[.no-wrap,{{#if outputLanguage}}{{outputLanguage}}{{else}}bash{{/if}}]
+----
+{{{output}}}
+----
+{{/if}}
+
+{{~else if (eq type "examples")~}}
+{{!-- Examples section at level 2 (==) --}}
+== {{#if title}}{{title}}{{else}}Examples{{/if}}
+
+This section provides examples of how to use `{{commandPath}}`.
+
+{{#each items}}
+{{#if description}}
+{{{description}}}.
+
+{{/if}}
+[,{{#if language}}{{language}}{{else}}bash{{/if}}{{#if attributes}}{{#each attributes}}{{#if @first}},{{/if}}{{@key}}="{{this}}"{{/each}}{{/if}}]
+----
+{{{code}}}
+----
+{{#if output}}
+
+Output:
+
+[.no-wrap,{{#if outputLanguage}}{{outputLanguage}}{{else}}bash{{/if}}]
+----
+{{{output}}}
+----
+{{/if}}
+
+{{/each}}
+{{~else if (eq type "section")~}}
+{{!-- Custom section with optional subsections --}}
+{{#if title}}
+{{!-- Determine heading level (default to 2 for ==) --}}
+{{#if headingLevel}}{{#repeat headingLevel}}={{/repeat}} {{title}}{{else}}== {{title}}{{/if}}
+
+{{#if (eq title "Examples")}}
+This section provides examples of how to use `{{commandPath}}`.
+
+{{/if}}
+{{/if}}
+{{#if subsections}}
+{{!-- Render subsections recursively --}}
+{{!-- Parent section defaults to level 2 (==), so subsections start at level 3 (===) --}}
+{{#each subsections}}
+{{> subsection this headingLevel=(add (default ../headingLevel 2) 1)}}
+{{/each}}
+{{else}}
+{{!-- No subsections, render content directly --}}
+{{{content}}}
+
+{{/if}}
+{{~else if (eq type "cloud-only")~}}
+{{!-- Cloud-only content (already wrapped by generator) --}}
+{{{content}}}
+
+{{~else if (eq type "self-hosted")~}}
+{{!-- Self-hosted content (already wrapped by generator) --}}
+{{{content}}}
+
+{{~else if (eq type "note")~}}
+{{!-- Note admonition --}}
+{{{content}}}
+
+{{~else if (eq type "warning")~}}
+{{!-- Warning admonition --}}
+{{{content}}}
+
+{{~else if (eq type "tip")~}}
+{{!-- Tip admonition --}}
+{{{content}}}
+
+{{~else if (eq type "caution")~}}
+{{!-- Caution admonition --}}
+{{{content}}}
+
+{{~else if (eq type "important")~}}
+{{!-- Important admonition --}}
+{{{content}}}
+
+{{~else~}}
+{{!-- Fallback for unknown types - render as-is --}}
+{{#if title}}
+== {{title}}
+
+{{/if}}
+{{{content}}}
+
+{{~/if~}}

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

@@ -0,0 +1,37 @@
+{{!-- Recursively render a subsection --}}
+{{!-- Default to === for first level subsections, increase for nested --}}
+{{#if headingLevel}}{{#repeat headingLevel}}={{/repeat}} {{title}}{{else}}=== {{title}}{{/if}}
+
+{{#if content}}
+{{{content}}}
+
+{{/if}}
+{{#if items}}
+{{!-- Render items as examples --}}
+{{#each items}}
+{{#if description}}
+{{{description}}}
+
+{{/if}}
+[,{{#if language}}{{language}}{{else}}bash{{/if}}]
+----
+{{{code}}}
+----
+{{#if output}}
+
+Output:
+
+[.no-wrap,{{#if outputLanguage}}{{outputLanguage}}{{else}}bash{{/if}}]
+----
+{{{output}}}
+----
+{{/if}}
+
+{{/each}}
+{{/if}}
+{{#if subsections}}
+{{!-- Recursively render nested subsections with increased heading level --}}
+{{#each subsections}}
+{{> subsection this headingLevel=(add ../headingLevel 1)}}
+{{/each}}
+{{/if}}