@redpanda-data/docs-extensions-and-macros 4.12.5 → 4.13.0

package/macros/DEVELOPMENT.adoc

@@ -0,0 +1,377 @@
+= AsciiDoc Macros Development Guide
+:toc:
+:toclevels: 3
+
+Guide for developing new AsciiDoc macros.
+
+AsciiDoc macros extend AsciiDoc syntax with custom inline and block elements. Macros are Asciidoctor.js extensions that process custom syntax and generate HTML output.
+
+== Macro types
+
+=== Inline macros
+
+Inline macros appear within text and generate inline HTML:
+
+[,asciidoc]
+----
+Text with glossterm:term[] inline.
+----
+
+=== Block macros
+
+Block macros appear on their own lines and generate block-level HTML:
+
+[,asciidoc]
+----
+component_table::[]
+----
+
+== Creating an inline macro
+
+=== Create the file
+
+[,bash]
+----
+touch macros/my-macro.js
+----
+
+=== Implement the macro
+
+[,javascript]
+----
+module.exports.register = function register (registry, context) {
+  // Register inline macro
+  registry.inlineMacro('mymacro', function () {
+    const self = this
+
+    // Define macro processing
+    self.process(function (parent, target, attrs) {
+      // target: the value after the colon
+      // attrs: positional and named attributes
+
+      // Generate HTML
+      const html = `<span class="my-macro">${target}</span>`
+
+      // Return as passthrough
+      return self.createInline(parent, 'quoted', html, { type: 'unquoted' })
+    })
+  })
+}
+----
+
+=== Register in playbook
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - './macros/my-macro.js'
+----
+
+=== Use in AsciiDoc
+
+[,asciidoc]
+----
+This is my mymacro:example[] macro.
+----
+
+== Creating a block macro
+
+[,javascript]
+----
+module.exports.register = function register (registry, context) {
+  registry.blockMacro('myblock', function () {
+    const self = this
+
+    self.process(function (parent, target, attrs) {
+      // Generate block HTML
+      const html = `
+        <div class="my-block">
+          <h3>${target}</h3>
+          <p>${attrs.content || 'No content'}</p>
+        </div>
+      `
+
+      // Return as passthrough block
+      return self.createBlock(parent, 'pass', html)
+    })
+  })
+}
+----
+
+Use in AsciiDoc:
+
+[,asciidoc]
+----
+myblock::title[content=Some content here]
+----
+
+== Common patterns
+
+=== Accessing attributes
+
+[,javascript]
+----
+self.process(function (parent, target, attrs) {
+  // Positional attributes
+  const first = attrs.$positional[0]
+  const second = attrs.$positional[1]
+
+  // Named attributes
+  const name = attrs.name
+  const value = attrs.value || 'default'
+
+  // Document attributes
+  const docAttr = parent.getDocument().getAttribute('my-attr')
+
+  return self.createInline(parent, 'quoted', html, { type: 'unquoted' })
+})
+----
+
+=== Generating links
+
+[,javascript]
+----
+self.process(function (parent, target, attrs) {
+  const url = `https://example.com/${target}`
+  const text = attrs.text || target
+
+  const html = `<a href="${url}" class="external">${text}</a>`
+
+  return self.createInline(parent, 'quoted', html, { type: 'unquoted' })
+})
+----
+
+=== Accessing page context
+
+[,javascript]
+----
+module.exports.register = function register (registry, context) {
+  // Access Antora context
+  const { contentCatalog, file } = context
+
+  registry.inlineMacro('pagemacro', function () {
+    const self = this
+
+    self.process(function (parent, target, attrs) {
+      // Access current page
+      const doc = parent.getDocument()
+      const component = doc.getAttribute('page-component-name')
+      const version = doc.getAttribute('page-component-version')
+
+      // Access content catalog
+      const page = contentCatalog.getById({
+        component,
+        version,
+        module: 'ROOT',
+        family: 'page',
+        relative: `${target}.adoc`
+      })
+
+      if (page) {
+        const html = `<a href="${page.pub.url}">${page.asciidoc.doctitle}</a>`
+        return self.createInline(parent, 'quoted', html, { type: 'unquoted' })
+      }
+
+      return self.createInline(parent, 'quoted', target, { type: 'unquoted' })
+    })
+  })
+}
+----
+
+=== Creating complex HTML
+
+[,javascript]
+----
+self.process(function (parent, target, attrs) {
+  const items = attrs.items ? attrs.items.split(',') : []
+
+  const html = `
+    <div class="custom-list">
+      <ul>
+        ${items.map(item => `<li>${item.trim()}</li>`).join('\n')}
+      </ul>
+    </div>
+  `
+
+  return self.createBlock(parent, 'pass', html)
+})
+----
+
+=== Error handling
+
+[,javascript]
+----
+self.process(function (parent, target, attrs) {
+  try {
+    if (!target) {
+      console.warn('mymacro: target is required')
+      return self.createInline(parent, 'quoted', '[Missing target]', { type: 'unquoted' })
+    }
+
+    // Process macro
+    const html = `<span>${target}</span>`
+    return self.createInline(parent, 'quoted', html, { type: 'unquoted' })
+
+  } catch (err) {
+    console.error(`mymacro error: ${err.message}`)
+    return self.createInline(parent, 'quoted', '[Macro error]', { type: 'unquoted' })
+  }
+})
+----
+
+== Testing
+
+=== Unit tests
+
+[,javascript]
+----
+// macros/__tests__/my-macro.test.js
+const asciidoctor = require('@asciidoctor/core')()
+const myMacro = require('../my-macro')
+
+describe('my-macro', () => {
+  let registry
+
+  beforeEach(() => {
+    registry = asciidoctor.Extensions.create()
+    myMacro.register(registry)
+  })
+
+  test('processes inline macro', () => {
+    const html = asciidoctor.convert(
+      'Text with mymacro:value[] inline.',
+      { extension_registry: registry }
+    )
+
+    expect(html).toContain('class="my-macro"')
+    expect(html).toContain('value')
+  })
+})
+----
+
+=== Integration tests
+
+Test with Antora:
+
+[,bash]
+----
+npx antora --fetch local-antora-playbook.yml
+----
+
+== Best practices
+
+=== Validate input
+
+[,javascript]
+----
+if (!target) {
+  console.warn('Macro requires a target')
+  return self.createInline(parent, 'quoted', '', { type: 'unquoted' })
+}
+----
+
+=== Escape HTML
+
+[,javascript]
+----
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;')
+}
+
+const safeTarget = escapeHtml(target)
+const html = `<span>${safeTarget}</span>`
+----
+
+=== Provide defaults
+
+[,javascript]
+----
+const cssClass = attrs.class || 'default-class'
+const text = attrs.text || target || 'Default text'
+----
+
+=== Use semantic HTML
+
+[,javascript]
+----
+// Good
+const html = `<code class="property">${target}</code>`
+
+// Avoid
+const html = `<span class="code-like property">${target}</span>`
+----
+
+=== Document your macro
+
+[,javascript]
+----
+/**
+ * My Macro - Short description
+ *
+ * Syntax: mymacro:target[attr1,attr2]
+ *
+ * Parameters:
+ * - target: The target value (required)
+ * - attr1: First attribute (optional)
+ * - attr2: Second attribute (optional)
+ *
+ * Example:
+ * mymacro:example[foo,bar]
+ */
+module.exports.register = function register (registry, context) {
+  // Implementation
+}
+----
+
+== Debugging
+
+=== Enable logging
+
+[,javascript]
+----
+console.log('Macro target:', target)
+console.log('Macro attrs:', JSON.stringify(attrs, null, 2))
+console.log('Document attrs:', parent.getDocument().getAttributes())
+----
+
+=== Test locally
+
+Create a test AsciiDoc file:
+
+[,asciidoc]
+----
+= Test Page
+
+Testing mymacro:value[attr1,attr2] inline.
+----
+
+Convert directly:
+
+[,bash]
+----
+node -e "
+const asciidoctor = require('@asciidoctor/core')()
+const macro = require('./macros/my-macro')
+const registry = asciidoctor.Extensions.create()
+macro.register(registry)
+const html = asciidoctor.convertFile('test.adoc', {
+  extension_registry: registry,
+  to_file: false
+})
+console.log(html)
+"
+----
+
+== Related documentation
+
+* link:USER_GUIDE.adoc[User guide] - How to use macros
+* link:REFERENCE.adoc[Reference] - Complete macro documentation
+* https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/[Asciidoctor.js Extensions]
+* https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/inline-macro-processor/[Inline Macro Processor]
+* https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/block-macro-processor/[Block Macro Processor]

package/macros/README.adoc

@@ -0,0 +1,105 @@
+= AsciiDoc Macros
+:toc:
+:toclevels: 2
+
+Documentation for AsciiDoc macros and extensions for Redpanda documentation.
+
+== What are AsciiDoc macros?
+
+AsciiDoc macros are custom inline and block elements that extend AsciiDoc syntax. These macros provide specialized formatting, references, and dynamic content generation within documentation pages.
+
+== Documentation
+
+link:USER_GUIDE.adoc[**User guide**]:: How to use AsciiDoc macros in your documentation
++
+* Installation and setup
+* Using macros in AsciiDoc
+* Common usage patterns
+* Troubleshooting
+
+link:REFERENCE.adoc[**Reference**]:: Complete reference for all available macros
++
+* Macro descriptions
+* Syntax and parameters
+* Configuration options
+* Examples for each macro
+
+link:DEVELOPMENT.adoc[**Development guide**]:: How to develop new AsciiDoc macros
++
+* Macro architecture
+* Creating inline and block macros
+* Testing and debugging
+* Best practices
+
+== Quickstart
+
+=== Install the package
+
+[,bash]
+----
+npm i @redpanda-data/docs-extensions-and-macros
+----
+
+=== Configure in your playbook
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
+----
+
+IMPORTANT: Macros must be registered under the `asciidoc.extensions` key in your playbook, not `antora.extensions`.
+
+== Available macros
+
+=== Inline macros
+
+* **glossterm** - Reference glossary terms with tooltips
+* **config_ref** - Link to configuration properties
+* **helm_ref** - Link to Helm chart values
+* **badge** - Display status badges
+
+=== Block macros
+
+* **components_by_category** - Display Redpanda Connect components grouped by category
+* **component_table** - Generate searchable component tables
+* **component_type_dropdown** - Create dropdown for component types
+
+See link:REFERENCE.adoc[Reference documentation] for complete details on each macro.
+
+== Common use cases
+
+=== Reference glossary terms
+
+[,asciidoc]
+----
+The glossterm:partition[partition] contains the data.
+----
+
+=== Link to configuration
+
+[,asciidoc]
+----
+Configure the config_ref:retention.ms,true,topic-properties[] property.
+----
+
+=== Link to Helm values
+
+[,asciidoc]
+----
+For configuration options, see the helm_ref:storage.tieredConfig.cloud_storage_enabled[] value.
+----
+
+=== Display Redpanda Connect components
+
+[,asciidoc]
+----
+components_by_category::inputs[]
+----
+
+== Support
+
+* link:USER_GUIDE.adoc#troubleshooting[Troubleshooting guide]
+* https://github.com/redpanda-data/docs-extensions-and-macros/issues[Report issues]
+* https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/[Asciidoctor.js Extensions]

package/macros/REFERENCE.adoc

@@ -0,0 +1,222 @@
+= AsciiDoc macros reference
+:toc:
+:toclevels: 3
+
+Reference documentation for all AsciiDoc macros and extensions provided by this library.
+
+IMPORTANT: Be sure to register each extension under the `asciidoc.extensions` key in the playbook, not the `antora.extensions` key.
+
+== Add line numbers and highlights
+
+This extension adds the necessary classes to make line numbers and line highlighting work with Prism.js.
+
+=== Registration
+
+```yaml
+antora:
+  extensions:
+  - '@redpanda-data/docs-extensions-and-macros/asciidoc-extensions/add-line-numbers-highlights'
+```
+
+== config_ref
+
+This inline macro is used to generate a reference to a configuration value in the Redpanda documentation. The macro's parameters allow for control over the generated reference's format and the type of output produced.
+
+=== Usage
+
+The `config_ref` macro is used in an AsciiDoc document as follows:
+
+[,asciidoc]
+----
+config_ref:configRef,isLink,path[]
+----
+
+The `config_ref` macro takes three parameters:
+
+configRef::
+This is the configuration reference, which is also used to generate the anchor link if `isLink` is `true`.
+
+isLink::
+Whether the output should be a link. If `isLink` is set to `true`, the output will be a cross-reference (xref) to the relevant configuration value.
+
+path::
+This is the path to the document where the configuration value is defined. This parameter is used to to generate the link if `isLink` is `true`.
+
+IMPORTANT: The path must be the name of a document at the root of the `reference` module.
+
+NOTE: The `config_ref` macro is environment-aware. It checks if the document it is being used in is part of a Kubernetes environment by checking if the `env-kubernetes` attribute is set in the document's attributes. Depending on this check, it either prepends `storage.tieredConfig.` to the `configRef` or just uses the `configRef` as is.
+
+For example:
+
+[,asciidoc]
+----
+config_ref:example_config,true,tunable-properties[]
+----
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
+----
+
+== glossterm
+
+The `glossterm` inline macro provides a way to define and reference glossary terms in your AsciiDoc documents.
+
+NOTE: This macro is a customized version of https://gitlab.com/djencks/asciidoctor-glossary[`asciidoctor-glossary`].
+
+=== Usage
+
+Use the `glossterm` inline macro to reference a term within the text of the document:
+
+[,asciidoc]
+----
+glossterm:my term[myDefinition]
+----
+
+It takes two parameters:
+
+term::
+The term to be defined.
+
+definition (optional)::
+The definition of the term. If the term is defined in the https://github.com/redpanda-data/docs-site[`shared` component] or the `local-terms` object of the `antora.yml` file, you can omit the definition as it will always be replaced by those definitions.
+
+=== Configuration options
+
+glossary-log-terms (optional)::
+Whether to log a textual representation of a definition list item to the console.
+
+glossary-term-role (optional)::
+Role to assign each term. By default, glossary terms are assigned the `glossary-term` role, which gives them the class `glossary-term` in generated html.
+
+glossary-links (optional)::
+Whether to generate links to glossary entries.
+By default, links to the glossary entries are generated from the glossary terms. To avoid this, set the attribute to `false` as either asciidoctor configuration or a header attribute.
+
+glossary-page (optional)::
+Target page for glossary links. By default, links are generated to the same page as the glossary term. To specify the target page, set this attribute to the resource ID of a page where the `glossary` block macro is used.
+
+glossary-tooltip (optional)::
+Whether to enable tooltips for the defined terms. Valid values are:
+- title: This uses the browser built-in `title` attribute to display the definition.
+
+- true: This inserts the definition as the value of the attribute `data-glossary-tooltip`.
+
+- data-<attribute-name>​: This inserts the definition as the value of the supplied attribute name, which must start with `data`.
+
+The last two options are intended to support js/css tooltip solutions such as tippy.js.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
+----
+
+== helm_ref
+
+This is an inline macro to create links to a Helm `values.yaml` file on ArtifactHub.
+
+=== Usage
+
+In an AsciiDoc document, use the `helm_ref` macro as follows:
+
+[,asciidoc]
+----
+helm_ref:<helmRef>[]
+----
+
+Where `<helmRef>` is the Helm configuration value you want to reference in the `values.yaml` file.
+
+For example:
+
+Given a Helm reference value of `myConfigValue`, you would use the macro like this:
+
+[,asciidoc]
+----
+helm_ref:myConfigValue[]
+----
+
+This will generate the following output:
+
+[,asciidoc]
+----
+For default values and documentation for configuration options, see the https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=myConfigValue[values.yaml] file.
+----
+
+If you do not specify a Helm reference value, the macro generates a link without specifying a path.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
+----
+
+== components_by_category
+
+This macro generates a tabbed interface to display Redpanda Connect components by category.
+
+The categories are fetched from the `connectCategoriesData` that's generated in the Component category aggregator extension.
+
+=== Usage
+
+```asciidoc
+components_by_category::[<type>]
+```
+
+=== Registration
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```
+
+== component_table
+
+This macro generates a searchable table of all Redpanda Connect components with filters for support and type.
+
+The types are fetched from the `flatComponentsData` that's generated in the Component category aggregator extension.
+
+=== Usage
+
+```asciidoc
+component_table::[]
+```
+
+=== Registration
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```
+
+== component_type_dropdown
+
+This macro generates a dropdown of other supported types for a particular component, allowing users to switch between different types.
+
+The types are fetched from the `flatComponentsData` that's generated in the Component category aggregator extension.
+
+=== Usage
+
+```asciidoc
+component_type_dropdown::[]
+```
+
+=== Registration
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```