npm - @redpanda-data/docs-extensions-and-macros - Versions diffs - 4.15.3 → 4.15.5 - Mend

@redpanda-data/docs-extensions-and-macros 4.15.3 → 4.15.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/extensions/add-faq-structured-data.js +53 -21
package/extensions/convert-llms-to-txt.js +7 -0
package/package.json +2 -1

package/extensions/add-faq-structured-data.js CHANGED Viewed

@@ -5,27 +5,65 @@
  *
  * USAGE:
  *   :page-faq-1-question: How do I install Redpanda?
- *   :page-faq-1-answer: Download from redpanda.com and run the installer.
+ *   :page-faq-1-answer: Download from redpanda.com and run the installer. See our xref:get-started:intro.adoc[quickstart guide] for details.
  *   :page-faq-1-anchor: #installation (optional - links to section)
  *
  *   :page-faq-2-question: What are the system requirements?
- *   :page-faq-2-answer: You need at least 2GB RAM and 2 CPU cores.
+ *   :page-faq-2-answer: You need at least 2GB RAM and 2 CPU cores for production. For development, xref:deploy:docker-compose.adoc[use Docker Compose].
  *   :page-faq-2-anchor: #requirements
  *
  * The extension:
  * - Generates schema.org FAQPage JSON-LD in <head>
  * - Supports multiple FAQs numbered sequentially (1, 2, 3...)
  * - Anchor is optional and adds URL to the FAQ question
- * - Writers can reference existing page content in answers
+ * - Writers can use AsciiDoc xrefs in answers - they're resolved to full URLs
+ * - Xrefs are converted to "link text (URL)" format in JSON-LD
  */
+/**
+ * Resolve xrefs in text to full URLs
+ * @param {string} text - Text containing xref macros
+ * @param {Object} currentPage - Current page context
+ * @param {Object} contentCatalog - Antora content catalog
+ * @param {string} siteUrl - Base site URL
+ * @param {Object} logger - Logger instance
+ * @returns {string} Text with xrefs resolved to plain text + URLs
+ */
+function resolveXrefs(text, currentPage, contentCatalog, siteUrl, logger) {
+  // Match xref:target[link text] pattern
+  const xrefPattern = /xref:([^\[]+)\[([^\]]+)\]/g
+  return text.replace(xrefPattern, (match, target, linkText) => {
+    try {
+      // Resolve the resource using Antora's content catalog
+      // This uses Antora's standard API for resolving page references
+      const resource = contentCatalog.resolveResource(target, currentPage.src, 'page')
+      if (resource && resource.pub && resource.pub.url) {
+        const fullUrl = siteUrl ? `${siteUrl}${resource.pub.url}` : `https://docs.redpanda.com${resource.pub.url}`
+        return `${linkText} (${fullUrl})`
+      } else {
+        // Xref couldn't be resolved (page doesn't exist or isn't loaded yet)
+        // Fall back to just the link text - this is expected for cross-component refs in local builds
+        return linkText
+      }
+    } catch (error) {
+      logger.warn(`FAQ xref resolution error for ${target}: ${error.message}`)
+      return linkText // Fallback to just the link text
+    }
+  })
+}
 /**
  * Extract FAQ entries from page attributes
  * @param {Object} attributes - Page attributes object
+ * @param {Object} page - Current page object
+ * @param {Object} contentCatalog - Antora content catalog
+ * @param {string} siteUrl - Base site URL
  * @param {Object} logger - Logger instance
  * @returns {Array<{question: string, answer: string, anchor?: string}>}
  */
-function extractFaqs(attributes, logger) {
+function extractFaqs(attributes, page, contentCatalog, siteUrl, logger) {
   const faqs = []
   const faqNumbers = new Set()
@@ -58,9 +96,12 @@ function extractFaqs(attributes, logger) {
       return
     }
+    // Resolve any xrefs in the answer text
+    const resolvedAnswer = resolveXrefs(answer.trim(), page, contentCatalog, siteUrl, logger)
     const faq = {
       question: question.trim(),
-      answer: answer.trim()
+      answer: resolvedAnswer
     }
     if (anchor) {
@@ -115,35 +156,26 @@ module.exports.register = function () {
   this.on('documentsConverted', ({ contentCatalog }) => {
     const pages = contentCatalog.getPages()
+    const siteUrl = playbook?.site?.url || ''
     let processedCount = 0
     let totalFaqs = 0
-    const siteUrl = playbook?.site?.url || 'https://docs.redpanda.com'
     pages.forEach(page => {
       const attributes = page.asciidoc?.attributes
       if (!attributes) return
-      // Extract FAQs from attributes
-      const faqs = extractFaqs(attributes, logger)
+      // Extract FAQs from attributes and resolve any xrefs
+      const faqs = extractFaqs(attributes, page, contentCatalog, siteUrl, logger)
       if (faqs.length === 0) return
-      // Generate base URL for the page
-      let baseUrl = ''
-      if (page.pub?.url) {
-        baseUrl = `${siteUrl}${page.pub.url}`
-      }
-      // Generate FAQPage JSON-LD
-      const faqJsonLd = generateFaqJsonLd(faqs, baseUrl)
-      // Store as JSON string in page attribute for UI template
-      attributes['page-faq-json-ld'] = JSON.stringify(faqJsonLd, null, 2)
+      // Store structured FAQ data as JSON for UI template to format
+      // Template will generate the JSON-LD structure using page.url
+      attributes['page-has-faqs'] = 'true'
+      attributes['page-faqs'] = JSON.stringify(faqs)
       processedCount++
       totalFaqs += faqs.length
-      logger.debug(`Added ${faqs.length} FAQs to ${page.src.relative}`)
     })
     if (processedCount > 0) {

package/extensions/convert-llms-to-txt.js CHANGED Viewed

@@ -80,11 +80,18 @@ module.exports.register = function () {
         // The markdown converter applies smart typography that turns -- into — (em dash)
         // and inserts zero-width spaces (U+200B) and other invisible Unicode characters
         // This breaks URLs like deploy-preview-159--redpanda-documentation.netlify.app
+        // Fix URLs in parentheses (actual hrefs)
         content = content.replace(/\(https?:\/\/[^)]*[—\u200B-\u200D\uFEFF][^)]*\)/g, (match) => {
           return match
             .replace(/—/g, '--')
             .replace(/[\u200B-\u200D\uFEFF]/g, '');
         });
+        // Fix URLs in square brackets (link text)
+        content = content.replace(/\[https?:\/\/[^\]]*[—\u200B-\u200D\uFEFF][^\]]*\]/g, (match) => {
+          return match
+            .replace(/—/g, '--')
+            .replace(/[\u200B-\u200D\uFEFF]/g, '');
+        });
         logger.debug('Fixed em dashes and invisible characters in URLs');
         // Unpublish the HTML page FIRST (following unpublish-pages pattern)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.15.3",
+  "version": "4.15.5",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -59,6 +59,7 @@
     "./extensions/generate-index-data": "./extensions/generate-index-data.js",
     "./extensions/generate-rp-connect-info": "./extensions/generate-rp-connect-info.js",
     "./extensions/add-global-attributes": "./extensions/add-global-attributes.js",
+    "./extensions/git-full-clone": "./extensions/git-full-clone.js",
     "./extensions/add-git-dates": "./extensions/add-git-dates.js",
     "./extensions/add-faq-structured-data": "./extensions/add-faq-structured-data.js",
     "./extensions/version-fetcher/set-latest-version": "./extensions/version-fetcher/set-latest-version.js",