@redpanda-data/docs-extensions-and-macros 5.22.1 → 5.22.2

package/bin/doc-tools.js

@@ -901,7 +901,7 @@ automation
  * @description
  * One-time migration that rewires published connector reference pages onto the
  * regenerated description partial: the header `:description:` becomes
- * `include::...[tag=attrs]` and the frozen intro prose becomes
+ * `include::...[tag=meta]` and the frozen intro prose becomes
  * `include::...[tag=body]`. Afterwards `generate rpcn-connector-docs` keeps
  * both fresh on every run.
  *

package/extensions/README.adoc

@@ -64,7 +64,6 @@ IMPORTANT: Extensions must be registered under the `antora.extensions` key in yo
 
 === Navigation
 * **unlisted-pages** - Manage pages that appear in navigation but aren't listed
-* **produce-redirects** - Generate redirect configurations
 * **unpublish-pages** - Mark pages as unpublished
 
 === Integrations
@@ -125,13 +124,16 @@ antora:
       algolia_index_name: YOUR_INDEX
 ----
 
-=== Generate redirects
+=== Redirects
+
+No extension required: core Antora (>= 3.1.8) generates redirects for https://docs.antora.org/antora/latest/page/page-aliases/[page aliases] automatically on every build. Define aliases in your `antora.yml`:
 
 [,yaml]
 ----
-antora:
-  extensions:
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
+name: redpanda
+asciidoc:
+  attributes:
+    page-aliases: old-page.adoc,another-old-page.adoc
 ----
 
 == Support

package/extensions/REFERENCE.adoc

@@ -706,23 +706,7 @@ In this example, the `attributespath` option points to a local YAML file (`./loc
 
 == Produce redirects (customization of core Antora)
 
-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.
-
-=== Environment variables
-
-This extension does not require any environment variables.
-
-=== Configuration options
-
-There are no configurable options for this extension.
-
-=== Registration
-
-```yaml
-antora:
-  extensions:
-  - '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects'
-```
+Antora's built-in `@antora/redirect-producer` already produces redirect rules for https://docs.antora.org/antora/latest/page/page-aliases/[page aliases], including the redirect-loop case caused by https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/#html-extension-style-key[`indexify`] that once required a workaround. Antora runs the real module automatically on every build with no extension required. This project previously shipped a hand-copied override of that module to work around the loop, but the override had drifted from the upstream fix and reintroduced a worse bug (a self-referential alias could overwrite the real page it pointed at). The override has been removed; core Antora handles redirects natively.
 
 == Replace attributes in attachments
 

package/extensions/USER_GUIDE.adoc

@@ -85,7 +85,6 @@ antora:
   extensions:
     - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version'
     - '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data.js'
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
 ----
 
 Extensions run in the order they're listed.
@@ -122,16 +121,7 @@ antora:
 
 === Redirect management
 
-Generate redirects from old URLs to new ones:
-
-[,yaml]
-----
-antora:
-  extensions:
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
-----
-
-Define redirects in your `antora.yml`:
+No extension required: core Antora (>= 3.1.8) generates redirects for old URLs automatically. Define redirects in your `antora.yml`:
 
 [,yaml]
 ----

package/macros/glossary.js

@@ -4,6 +4,61 @@ const $glossaryContexts = Symbol('$glossaryContexts')
 const { posix: path } = require('path')
 const chalk = require('chalk')
 
+// Backtick-monospace in hover-text. The unconstrained (double-backtick) form is
+// matched first, otherwise it leaves a stray delimiter on each side.
+const MONOSPACE_RX = /``([^`]+)``|`([^`]+)`/g
+
+// Escape for interpolation into a double-quoted HTML attribute. Same four
+// replacements, in the same order, as badge.js and enterprise.js; `&` has to go
+// first or it re-escapes the entities the later passes introduce.
+function escapeAttr (value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+// Only a data-* tooltip is read by a JS tooltip library that renders it as HTML;
+// the native title attribute is always plain text. Shared with the
+// glossary-tooltip validation below so the two cannot drift apart.
+function tooltipRendersHtml (tooltipAttr) {
+  return typeof tooltipAttr === 'string' && tooltipAttr.startsWith('data-')
+}
+
+// hover-text is raw, unconverted source text, so it has to be escaped before it
+// lands in an HTML attribute. How many passes depends on the consumer:
+//
+//   title   The browser decodes the attribute once and shows the result as
+//           text, so one pass is exactly right.
+//   data-*  docs-ui initializes tippy on these with allowHTML: true
+//           (docs-ui/src/js/12-activate-tooltips.js), which means the value is
+//           decoded once by the HTML parser and then parsed AGAIN as HTML by
+//           innerHTML. A single pass is spent on that first decode and escaped
+//           markup comes back to life -- `<img onerror=...>` in hover-text
+//           became a live element that fired. Escape twice so one level
+//           survives the decode, and add <code> afterwards so it is the only
+//           live markup in the value.
+//
+// Set definitionIsHtml for a definition that Asciidoctor already converted --
+// the inline glossterm:term[definition] form arrives as HTML, unlike a term
+// file's raw :hover-text: value -- so it is escaped once rather than twice and
+// its markup survives to the reader instead of being shown as literal tags.
+function formatTooltipDefinition (text, tooltipAttr, definitionIsHtml) {
+  if (!tooltipRendersHtml(tooltipAttr)) return escapeAttr(text)
+  if (definitionIsHtml) {
+    // Already HTML, so one pass is right: the attribute decode hands the markup
+    // back intact for innerHTML to render, and a quote in the text still cannot
+    // terminate the attribute early.
+    return escapeAttr(text)
+  }
+  return escapeAttr(escapeAttr(text)).replace(
+    MONOSPACE_RX,
+    (match, unconstrained, constrained) =>
+      `<code>${unconstrained !== undefined ? unconstrained : constrained}</code>`
+  )
+}
+
 module.exports.register = function (registry, config = {}) {
 
   const vfs = adaptVfs()
@@ -113,19 +168,24 @@ module.exports.register = function (registry, config = {}) {
         }
         var tooltip = document.getAttribute('glossary-tooltip')
         if (tooltip === 'true') tooltip = 'data-glossary-tooltip'
-        if (tooltip && tooltip !== 'title' && !tooltip.startsWith('data-')) {
+        if (tooltip && tooltip !== 'title' && !tooltipRendersHtml(tooltip)) {
           console.log(`glossary-tooltip attribute '${tooltip}' must be 'true', 'title', or start with 'data-`)
           tooltip = undefined
         }
         const logTerms = document.hasAttribute('glossary-log-terms')
         var definition;
         var pageTitle;
+        // A term file's :hover-text: is raw source text, but the definition
+        // passed inline as glossterm:term[definition] has already been through
+        // Asciidoctor's inline substitutions, so the two need different escaping.
+        var definitionIsHtml = false;
         const index = context.gloss.findIndex((candidate) => candidate.term === term)
         if (index >= 0) {
           definition = context.gloss[index].def
           pageTitle = context.gloss[index].pageTitle
         } else {
           definition = attributes.definition;
+          definitionIsHtml = !!definition;
         }
         if (definition) {
           logTerms && console.log(`${term}:: ${definition}`)
@@ -154,12 +214,13 @@ module.exports.register = function (registry, config = {}) {
           inline = self.createInline(parent, 'quoted', customText, { attributes: attrs })
         }
         if (tooltip) {
+          const formattedDefinition = formatTooltipDefinition(definition, tooltip, definitionIsHtml)
           const a = inline.convert()
           const matches = a.match(TRX)
           if (matches) {
-            return self.createInline(parent, 'quoted', `${matches[1]} ${tooltip}="${definition}"${matches[2]}`)
+            return self.createInline(parent, 'quoted', `${matches[1]} ${tooltip}="${formattedDefinition}"${matches[2]}`)
           } else {
-            return self.createInline(parent, 'quoted', `<span ${tooltip}="${definition}">${a}</span>`)
+            return self.createInline(parent, 'quoted', `<span ${tooltip}="${formattedDefinition}">${a}</span>`)
           }
         }
         return inline
@@ -186,3 +247,5 @@ module.exports.register = function (registry, config = {}) {
   }
   return registry
 }
+
+module.exports.formatTooltipDefinition = formatTooltipDefinition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.22.1",
+  "version": "5.22.2",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -77,8 +77,6 @@
     "./extensions/find-related-labs": "./extensions/find-related-labs.js",
     "./extensions/convert-llms-to-txt": "./extensions/convert-llms-to-txt.js",
     "./extensions/convert-sitemap-to-markdown": "./extensions/convert-sitemap-to-markdown.js",
-    "./extensions/modify-redirects": "./extensions/produce-redirects.js",
-    "./extensions/produce-redirects": "./extensions/produce-redirects.js",
     "./extensions/algolia-indexer/index": "./extensions/algolia-indexer/index.js",
     "./extensions/aggregate-terms": "./extensions/aggregate-terms.js",
     "./extensions/resolve-xrefs-in-attachments": "./extensions/resolve-xrefs-in-attachments.js",

package/tools/redpanda-connect/generate-rpcn-connector-docs.js

@@ -43,8 +43,8 @@ const STALE_METADATA_PARTIAL =
 // deleting the file would break any published page that includes it, so blank
 // it instead and log so a human removes the include line.
 //
-// The empty attrs/body regions are load-bearing. Pages include this file with
-// `[tag=attrs]` and `[tag=body]`, and Asciidoctor logs `tag 'attrs' not found
+// The empty meta/body regions are load-bearing. Pages include this file with
+// `[tag=meta]` and `[tag=body]`, and Asciidoctor logs `tag 'meta' not found
 // in include file` for every tag a target does not define -- so a banner
 // without the regions turns one blanked partial into two build warnings on
 // every page that includes it, on every build, which is a build failure
@@ -54,7 +54,7 @@ const STALE_DESCRIPTION_PARTIAL =
   '// This content is autogenerated. Do not edit manually. ' +
   'The connector no longer has a description, so this partial is intentionally empty. ' +
   'You can remove the include directive that points at this file from the connector page.\n' +
-  '\n// tag::attrs[]\n// end::attrs[]\n' +
+  '\n// tag::meta[]\n// end::meta[]\n' +
   '\n// tag::body[]\n// end::body[]\n';
 
 // Component families with their own reference pages, keyed by the canonical
@@ -606,12 +606,12 @@ async function generateRpcnConnectorDocs(options) {
           // connectors with neither summary nor description, keep the inline
           // text rather than getting an include that cannot resolve.
           item.hasDescriptionPartial = true;
-          // The attrs region only sets :description: when the connector has a
+          // The meta region only sets :description: when the connector has a
           // summary, so a page may only replace its header attribute with the
           // include when there is one. Otherwise the page would lose its meta
           // description entirely and keep the inline attribute instead.
           if (typeof item.summary === 'string' && item.summary.trim()) {
-            item.hasDescriptionAttrs = true;
+            item.hasDescriptionMeta = true;
           }
           if (!writeFullDrafts) {
             partialsWritten++;
@@ -988,7 +988,7 @@ function backfillPageDescriptions (connectorData, { pagesRoot, dryRun = false }
       const lines = content.split('\n');
       const headerEnd = lines.findIndex((l) => l.trim() === '');
       const header = lines.slice(0, headerEnd === -1 ? lines.length : headerEnd);
-      // A page migrated to the description partial carries the attrs include
+      // A page migrated to the description partial carries the meta include
       // instead of a literal :description:. Without this arm the backfill
       // splices a competing meta block into every migrated page, so the page
       // ends up with a dead include plus a hand-inserted attribute that
@@ -997,7 +997,7 @@ function backfillPageDescriptions (connectorData, { pagesRoot, dryRun = false }
 
       // Meta descriptions are read as plain text by search results, link
       // previews, and assistants, so the markup comes out mechanically. Same
-      // flattener the description partial's attrs region uses, so a page
+      // flattener the description partial's meta region uses, so a page
       // cannot publish one meta description before migrating to the partial
       // and a different one after.
       const summary = flattenToAttributeValue(item.summary);

package/tools/redpanda-connect/helpers/descriptionInclude.js

@@ -6,7 +6,7 @@ const { descriptionIncludeLine } = require('../metadata-utils.js');
  * Handlebars helper: emit the include directive for a connector's description
  * partial, optionally for one of its tag regions.
  *
- *   {{{descriptionInclude this 'attrs'}}}
+ *   {{{descriptionInclude this 'meta'}}}
  *   {{{descriptionInclude this 'body'}}}
  *
  * Drafted pages use this instead of freezing the summary and description into
@@ -16,7 +16,7 @@ const { descriptionIncludeLine } = require('../metadata-utils.js');
  * writes the file.
  *
  * @param {object} item connector data with `type`/`typeDir` and `name`
- * @param {string} [tag] `attrs` or `body`
+ * @param {string} [tag] `meta` or `body`
  * @returns {string}
  */
 module.exports = function descriptionInclude (item, tag) {

package/tools/redpanda-connect/helpers/summaryAttribute.js

@@ -7,7 +7,7 @@ const { flattenToAttributeValue } = require('../metadata-utils.js');
  * value suitable for the `:description:` page attribute (and therefore for the
  * page's `<meta name="description">`).
  *
- * Delegates to the shared flattener so the description partial's attrs region
+ * Delegates to the shared flattener so the description partial's meta region
  * and `backfillPageDescriptions` publish the same text for the same summary.
  * Collapsing whitespace alone is not enough: summaries carry xrefs, link
  * macros and inline code, and an unflattened value ships raw

package/tools/redpanda-connect/metadata-utils.js

@@ -248,10 +248,10 @@ function descriptionWithMetadataInclude (item) {
  * auto-generated summary and description from a regenerated partial instead of
  * freezing them into the page body at first draft.
  *
- * The partial defines two tag regions, so pages address it twice: `attrs` in
+ * The partial defines two tag regions, so pages address it twice: `meta` in
  * the page header (sets `:description:`) and `body` where the prose renders.
  * @param {object} item connector data with `type`/`typeDir` and `name`
- * @param {string} [tag] tag region to include (`attrs` or `body`); omit for the whole file
+ * @param {string} [tag] tag region to include (`meta` or `body`); omit for the whole file
  * @returns {string}
  */
 function descriptionIncludeLine (item, tag) {
@@ -308,7 +308,7 @@ function lostMetadataSections (oldContent, newContent) {
  * edited.
  *
  * This is the one implementation: `summaryAttribute` (the description
- * partial's attrs region) and `backfillPageDescriptions` (the page-header
+ * partial's meta region) and `backfillPageDescriptions` (the page-header
  * self-heal) both call it, so the two paths cannot drift into publishing
  * different meta descriptions for the same summary.
  *

package/tools/redpanda-connect/migrate-descriptions-to-partials.js

@@ -11,7 +11,7 @@
  * to `modules/components/partials/descriptions/<type>/<name>.adoc` on every
  * run, with two tag regions. This script rewires existing pages to it:
  *
- *   header: include::...[tag=attrs]  inside the page's `// tag::meta[]` region
+ *   header: include::...[tag=meta]   inside the page's `// tag::meta[]` region
  *   body:   include::...[tag=body]   where the frozen prose is today
  *
  * The header rewire is mechanical and safe: it swaps one `:description:` line
@@ -36,7 +36,7 @@ const path = require('path');
 const { descriptionIncludeLine, normalizeTypeDir, flattenToAttributeValue } = require('./metadata-utils.js');
 
 // The page's meta tag region: the block single-source stubs inherit
-// :description: from, so the attrs include belongs inside it.
+// :description: from, so the meta include belongs inside it.
 const META_TAG_OPEN = /^\/\/\s*tag::meta\[\]\s*$/;
 const META_TAG_CLOSE = /^\/\/\s*end::meta\[\]\s*$/;
 
@@ -123,34 +123,34 @@ function migrateDescriptionsToPartials ({
         continue;
       }
       const partial = fs.readFileSync(partialPath, 'utf8');
-      const attrs = tagRegion(partial, 'attrs');
+      const meta = tagRegion(partial, 'meta');
       const body = tagRegion(partial, 'body');
-      if (!attrs || !body || contentLines(body).length === 0) {
+      if (!meta || !body || contentLines(body).length === 0) {
         // A blanked partial (description removed upstream) has both regions
         // but no content. Wiring a page to it would publish an empty page.
         results.skipped.push({ page: key, reason: 'description partial is empty' });
         continue;
       }
 
-      const includeAttrs = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'attrs');
+      const includeMeta = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'meta');
       const includeBody = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'body');
 
       let lines = fs.readFileSync(pagePath, 'utf8').split('\n');
       let changed = false;
 
       // --- header ---------------------------------------------------------
-      if (!lines.some((l) => l.trim() === includeAttrs)) {
+      if (!lines.some((l) => l.trim() === includeMeta)) {
         const open = lines.findIndex((l) => META_TAG_OPEN.test(l));
         const close = lines.findIndex((l, i) => i > open && META_TAG_CLOSE.test(l));
-        const attrValue = contentLines(attrs)
+        const metaValue = contentLines(meta)
           .find((l) => l.startsWith(':description:'));
         const pageAttr = lines.slice(0, introOf(lines)).find((l) => l.startsWith(':description:'));
-        if (!attrValue) {
-          // The connector has no summary, so the attrs region sets nothing.
+        if (!metaValue) {
+          // The connector has no summary, so the meta region sets nothing.
           // Replacing a hand-written :description: with it would drop the
           // page's meta description.
-          results.skipped.push({ page: key, reason: 'attrs region sets no :description:' });
-        } else if (pageAttr && flattenToAttributeValue(pageAttr) !== flattenToAttributeValue(attrValue)) {
+          results.skipped.push({ page: key, reason: 'meta region sets no :description:' });
+        } else if (pageAttr && flattenToAttributeValue(pageAttr) !== flattenToAttributeValue(metaValue)) {
           // The page's meta description is not the connector summary, so it
           // was authored by hand (often tuned for search) and swapping in the
           // include would silently discard that editorial work. 13 pages in
@@ -159,7 +159,7 @@ function migrateDescriptionsToPartials ({
           // header alone.
           results.skipped.push({ page: key, reason: 'hand-authored :description: differs from the summary (needs a human)' });
         } else if (open !== -1 && close > open) {
-          lines.splice(open + 1, close - open - 1, includeAttrs);
+          lines.splice(open + 1, close - open - 1, includeMeta);
           results.headers.push(key);
           changed = true;
         } else {
@@ -169,7 +169,7 @@ function migrateDescriptionsToPartials ({
           // :description: lines in the first place.
           const attrLine = lines.findIndex((l) => l.startsWith(':description:'));
           if (attrLine !== -1 && attrLine < introOf(lines)) {
-            lines.splice(attrLine, 1, '// tag::meta[]', includeAttrs, '// end::meta[]');
+            lines.splice(attrLine, 1, '// tag::meta[]', includeMeta, '// end::meta[]');
             results.headers.push(key);
             changed = true;
           } else {
@@ -183,7 +183,7 @@ function migrateDescriptionsToPartials ({
       // it could not see and the page ended up with two. AsciiDoc takes the
       // last assignment, so leaving the literal one there would make the
       // include a no-op and the page would keep publishing frozen text.
-      if (lines.some((l) => l.trim() === includeAttrs)) {
+      if (lines.some((l) => l.trim() === includeMeta)) {
         for (let i = introOf(lines) - 1; i >= 0; i--) {
           if (lines[i].startsWith(':description:')) {
             lines.splice(i, 1);

package/tools/redpanda-connect/templates/connector.hbs

@@ -3,9 +3,9 @@
 :type: {{type}}
 {{#if support}}:support: {{support}}{{/if}}
 :categories: [{{join categories ", "}}]
-{{#if hasDescriptionAttrs}}
+{{#if hasDescriptionMeta}}
 // tag::meta[]
-{{{descriptionInclude this "attrs"}}}
+{{{descriptionInclude this "meta"}}}
 // end::meta[]
 {{else if summary}}
 // tag::meta[]
@@ -16,7 +16,7 @@
 :description: {{{summaryAttribute description}}}
 // end::meta[]
 {{/if}}
-{{!-- The attrs include stays inside the meta tag region so single-source
+{{!-- The meta include stays inside the meta tag region so single-source
      stubs keep inheriting :description: as a header attribute, and the
      value now refreshes with the connector instead of being frozen at
      first draft. Component families with no description partial keep the

package/tools/redpanda-connect/templates/descriptions-partials.hbs

@@ -2,12 +2,12 @@
 // This content is autogenerated. Do not edit manually. The summary and description come from the connector's definition in the Connect source. To change them, update the connector upstream, or use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
 //
 // Pages consume this partial in two places so both stay fresh:
-//   header: include::...[tag=attrs]  (sets :description: for search snippets and meta tags)
+//   header: include::...[tag=meta]  (sets :description: for search snippets and meta tags)
 //   body:   include::...[tag=body]   (renders the summary and description)
 
-// tag::attrs[]
+// tag::meta[]
 {{#if summary}}:description: {{{summaryAttribute summary}}}
-{{/if}}// end::attrs[]
+{{/if}}// end::meta[]
 
 // tag::body[]
 {{#if summary}}{{{summary}}}

package/extensions/produce-redirects.js

@@ -1,166 +0,0 @@
-'use strict';
-
-const { raiseListenerLimit } = require('./util/raise-listener-limit')
-
-const File = require('vinyl')
-const { posix: path } = require('path')
-
-const ENCODED_SPACE_RX = /%20/g
-
-module.exports.register = function () {
-  raiseListenerLimit(this)
-  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 = aliases.filter((it) => it.pub.url !== it.rel.pub.url)).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)
-        }
-      }
-    })
-  })
-}
-
-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) => {
-    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) => {
-    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) => {
-    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) {
-    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
-}
-