@redpanda-data/docs-extensions-and-macros 3.2.5 → 3.2.7

package/README.adoc

@@ -180,18 +180,9 @@ antora:
   - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-global-attributes'
 ```
 
-=== Modify redirects file
+=== Produce redirects (customization of core Antora)
 
-This extension removes redundant redirects from the Netlify redirects file. The need for this extension arises from an issue where the use of the `indexify` feature in Antora, combined with page aliases, can inadvertently create redirect loops or redundant redirects where the source and target URLs are identical.
-
-The issue is https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Redirect.20Loop.20Issue.20with.20Page.20Renaming.20and.20Indexify/near/433691700[recognized as a bug] within Antora's redirect producer, which does not currently
-check if the source and target URLs are the same before creating a redirect.
-
-The purpose of this script is to scan the `_redirects` file and remove any entries that point
-a URL to itself, which not only prevents redirect loops but also optimizes the redirect process
-by eliminating unnecessary entries. This cleanup helps ensure that the redirects file only contains valid and useful redirection rules.
-
-By integrating this script into the Antora pipeline, we ensure that each build's output is optimized and free from potential issues related to improper redirects, enhancing both site performance and user experience.
+This extension replaces the default https://gitlab.com/antora/antora/-/tree/v3.1.x/packages/redirect-producer[`produceRedirects()` function] in Antora to handle redirect loops caused by https://docs.antora.org/antora/latest/page/page-aliases/[page aliases]. Normally, page aliases in Antora are used to resolve outdated links without causing issues. However, with https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/#html-extension-style-key[`indexify`], the same URL may inadvertently be used for both the source and target of a redirect, leading to loops. This problem is https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Redirect.20Loop.20Issue.20with.20Page.20Renaming.20and.20Indexify/near/433691700[recognized as a bug] in core Antora. For example, creating a page alias for `modules/manage/security/authorization.adoc` to point to `modules/manage/security/authorization/index.adoc' can lead to a redirect loop where `manage/security/authorization/` points to `manage/security/authorization/`. Furthermore, omitting the alias would lead to `xref not found` errors because Antora relies on the alias to resolve the old xrefs. This extension is necessary until such behaviors are natively supported or fixed in Antora core.
 
 ==== Registration example
 

package/extensions/produce-redirects.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const File = require('vinyl')
+const { posix: path } = require('path')
+
+const ENCODED_SPACE_RX = /%20/g
+
+module.exports.register = function () {
+  this.once('contextStarted', () => {
+    const { publishFiles: produceRedirectsDelegate } = this.getFunctions()
+    this.replaceFunctions({
+      produceRedirects (playbook, aliases) {
+        if ('findBy' in aliases) aliases = aliases.findBy({ family: 'alias' }) // @deprecated remove in Antora 4
+        if (!aliases.length) return []
+        let siteUrl = playbook.site.url
+        if (siteUrl) siteUrl = stripTrailingSlash(siteUrl, '')
+        const directoryRedirects = (playbook.urls.htmlExtensionStyle || 'default') !== 'default'
+        switch (playbook.urls.redirectFacility) {
+          case 'gitlab':
+            return createNetlifyRedirects(aliases, extractUrlPath(siteUrl), !directoryRedirects, false)
+          case 'httpd':
+            return createHttpdHtaccess(aliases, extractUrlPath(siteUrl), directoryRedirects)
+          case 'netlify':
+            return createNetlifyRedirects(aliases, extractUrlPath(siteUrl), !directoryRedirects)
+          case 'nginx':
+            return createNginxRewriteConf(aliases, extractUrlPath(siteUrl))
+          case 'static':
+            return populateStaticRedirectFiles(
+              aliases.filter((it) => it.out),
+              siteUrl
+            )
+          default:
+            return unpublish(aliases)
+        }
+        return produceRedirectsDelegate.call(this, playbook, aliases)
+      }
+    })
+  })
+}
+
+function createStaticRedirectContents (file, siteUrl) {
+  const targetUrl = file.rel.pub.url
+  let linkTag
+  let to = targetUrl.charAt() === '/' ? computeRelativeUrlPath(file.pub.url, targetUrl) : undefined
+  let toText = to
+  if (to) {
+    if (siteUrl && siteUrl.charAt() !== '/') {
+      linkTag = `<link rel="canonical" href="${(toText = siteUrl + targetUrl)}">\n`
+    }
+  } else {
+    linkTag = `<link rel="canonical" href="${(toText = to = targetUrl)}">\n`
+  }
+  return `<!DOCTYPE html>
+<meta charset="utf-8">
+${linkTag || ''}<script>location="${to}"</script>
+<meta http-equiv="refresh" content="0; url=${to}">
+<meta name="robots" content="noindex">
+<title>Redirect Notice</title>
+<h1>Redirect Notice</h1>
+<p>The page you requested has been relocated to <a href="${to}">${toText}</a>.</p>`
+}
+
+function extractUrlPath (url) {
+  if (url) {
+    if (url.charAt() === '/') return url
+    const urlPath = new URL(url).pathname
+    return urlPath === '/' ? '' : urlPath
+  } else {
+    return ''
+  }
+}
+
+function createHttpdHtaccess (files, urlPath, directoryRedirects = false) {
+  const rules = files.reduce((accum, file) => {
+    if (isRedirectLoop(file)) return accum
+    delete file.out
+    let fromUrl = file.pub.url
+    fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
+    let toUrl = file.rel.pub.url
+    toUrl = ~toUrl.indexOf('%20') ? `'${urlPath}${toUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + toUrl
+    // see https://httpd.apache.org/docs/current/en/mod/mod_alias.html#redirect
+    // NOTE: redirect rule for directory prefix does not require trailing slash
+    if (file.pub.splat) {
+      accum.push(`Redirect 302 ${fromUrl} ${stripTrailingSlash(toUrl)}`)
+    } else if (directoryRedirects) {
+      accum.push(`RedirectMatch 301 ^${regexpEscape(fromUrl)}$ ${stripTrailingSlash(toUrl)}`)
+    } else {
+      accum.push(`Redirect 301 ${fromUrl} ${toUrl}`)
+    }
+    return accum
+  }, [])
+  return [new File({ contents: Buffer.from(rules.join('\n') + '\n'), out: { path: '.htaccess' } })]
+}
+
+// NOTE: a trailing slash on the pathname will be ignored
+// see https://docs.netlify.com/routing/redirects/redirect-options/#trailing-slash
+// however, we keep it when generating the rules for clarity
+function createNetlifyRedirects (files, urlPath, addDirectoryRedirects = false, useForceFlag = true) {
+  const rules = files.reduce((accum, file) => {
+    if (isRedirectLoop(file)) return accum
+    delete file.out
+    const fromUrl = urlPath + file.pub.url
+    const toUrl = urlPath + file.rel.pub.url
+    const forceFlag = useForceFlag ? '!' : ''
+    if (file.pub.splat) {
+      accum.push(`${fromUrl}/* ${ensureTrailingSlash(toUrl)}:splat 302${forceFlag}`)
+    } else {
+      accum.push(`${fromUrl} ${toUrl} 301${forceFlag}`)
+      if (addDirectoryRedirects && fromUrl.endsWith('/index.html')) {
+        accum.push(`${fromUrl.substr(0, fromUrl.length - 10)} ${toUrl} 301${forceFlag}`)
+      }
+    }
+    return accum
+  }, [])
+  return [new File({ contents: Buffer.from(rules.join('\n') + '\n'), out: { path: '_redirects' } })]
+}
+
+function createNginxRewriteConf (files, urlPath) {
+  const rules = files.map((file) => {
+    if (isRedirectLoop(file)) return ''
+    delete file.out
+    let fromUrl = file.pub.url
+    fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
+    let toUrl = file.rel.pub.url
+    toUrl = ~toUrl.indexOf('%20') ? `'${urlPath}${toUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + toUrl
+    if (file.pub.splat) {
+      const toUrlWithTrailingSlash = ensureTrailingSlash(toUrl)
+      return `location ^~ ${fromUrl}/ { rewrite ^${regexpEscape(fromUrl)}/(.*)$ ${toUrlWithTrailingSlash}$1 redirect; }`
+    } else {
+      return `location = ${fromUrl} { return 301 ${toUrl}; }`
+    }
+  })
+  return [new File({ contents: Buffer.from(rules.join('\n').trim() + '\n'), out: { path: '.etc/nginx/rewrite.conf' } })]
+}
+
+function populateStaticRedirectFiles(files, siteUrl) {
+  for (const file of files) {
+    if (isRedirectLoop(file)) continue
+    const content = createStaticRedirectContents(file, siteUrl) + '\n';
+    file.contents = Buffer.from(content);
+  }
+  return []
+}
+
+function unpublish (files) {
+  files.forEach((file) => delete file.out)
+  return []
+}
+
+function computeRelativeUrlPath (from, to) {
+  if (to === from) return to.charAt(to.length - 1) === '/' ? './' : path.basename(to)
+  return (path.relative(path.dirname(from + '.'), to) || '.') + (to.charAt(to.length - 1) === '/' ? '/' : '')
+}
+
+function ensureTrailingSlash (str) {
+  return str.charAt(str.length - 1) === '/' ? str : str + '/'
+}
+
+function stripTrailingSlash (str, root = '/') {
+  if (str === '/') return root
+  const lastIdx = str.length - 1
+  return str.charAt(lastIdx) === '/' ? str.substr(0, lastIdx) : str
+}
+
+function regexpEscape (str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // don't escape "-" since it's meaningless in a literal
+}
+
+function isRedirectLoop (file) {
+  if (file.pub.url === file.rel.pub.url) return true
+  return false
+}
+

package/macros/glossary.js

@@ -91,9 +91,10 @@ module.exports.register = function (registry, config = {}) {
       self.named('glossterm')
       //Specifying the regexp allows spaces in the term.
       self.$option('regexp', /glossterm:([^[]+)\[(|.*?[^\\])\]/)
-      self.positionalAttributes(['definition'])
+      self.positionalAttributes(['definition', 'customText']);
       self.process(function (parent, target, attributes) {
         const term = attributes.term || target
+        const customText = attributes.customText || term;
         const document = parent.document
         const context = vfs.getContext()
         const customLinkCandidate = context.gloss.find(candidate => 'link' in candidate && candidate.term === term);
@@ -136,10 +137,10 @@ module.exports.register = function (registry, config = {}) {
         const termExistsInContext = context.gloss.some((candidate) => candidate.term === term);
         if ((termExistsInContext && links) || (links && customLink)) {
           inline = customLink
-            ? self.createInline(parent, 'anchor', target, { type: 'link', target: customLink, attributes: { ...attrs, window: '_blank', rel: 'noopener noreferrer' } })
-            : self.createInline(parent, 'anchor', target, { type: 'xref', target: `${glossaryPage}#${termId(term)}`, reftext: target, attributes: attrs })
+            ? self.createInline(parent, 'anchor', customText, { type: 'link', target: customLink, attributes: { ...attrs, window: '_blank', rel: 'noopener noreferrer' } })
+            : self.createInline(parent, 'anchor', customText, { type: 'xref', target: `${glossaryPage}#${termId(term)}`, reftext: customText, attributes: attrs })
         } else {
-          inline = self.createInline(parent, 'quoted', target, { attributes: attrs })
+          inline = self.createInline(parent, 'quoted', customText, { attributes: attrs })
         }
         if (tooltip) {
           const a = inline.convert()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -35,7 +35,7 @@
     "./extensions/validate-attributes": "./extensions/validate-attributes.js",
     "./extensions/find-related-docs": "./extensions/find-related-docs.js",
     "./extensions/find-related-labs": "./extensions/find-related-labs.js",
-    "./extensions/modify-redirects": "./extensions/modify-redirects.js",
+    "./extensions/modify-redirects": "./extensions/produce-redirects.js",
     "./extensions/algolia-indexer/index": "./extensions/algolia-indexer/index.js",
     "./extensions/aggregate-terms": "./extensions/aggregate-terms.js",
     "./macros/glossary": "./macros/glossary.js",

package/extensions/modify-redirects.js

@@ -1,36 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-function redirectModifier(files, outputDir, logger) {
-  files.forEach((file) => {
-    const filePath = path.join(outputDir, file);
-    if (!fs.existsSync(filePath)) return
-    let content = fs.readFileSync(filePath, 'utf8');
-    const lines = content.split('\n');
-
-    // Filter out redirects that point to themselves
-    const modifiedLines = lines.filter((line) => {
-      const parts = line.split(' ');
-      if (parts[0] == parts[1]) logger.info(`Removed redirect that points to itself: ${line}`)
-      return parts[0] !== parts[1]; // Ensure the source and target are not the same
-    });
-
-    // Join the array back into a string and write it back to the file
-    const modifiedContent = modifiedLines.join('\n');
-    fs.writeFileSync(filePath, modifiedContent, 'utf8');
-    logger.info(`Processed and updated redirects in ${filePath}`);
-  })
-}
-
-module.exports.register = function ({ config }) {
-  const logger = this.getLogger('redirects-produced');
-  this.on('sitePublished', async ({ publications }) => {
-    publications.forEach(publication => {
-      const outputDir = publication.resolvedPath;
-      const redirectFile = ['_redirects'];
-      redirectModifier(redirectFile, outputDir, logger);
-    });
-  });
-};