Add archive attachments extension

[JakeSCahill]

• Added: archive-attachments extension to automate the archiving of grouped attachments based on configurable file patterns.
• Enhanced: replace-attributes-in-attachments extension by allowing customizable file patterns and user-defined replacement rules.
• Breaking change: The replace-attributes-in-attachments extension now requires configuration to specify which attachments should have their text replaced. Previously, the extension worked on all YAML attachments by default, which was inefficient as not all attachments required replacements.

Motivation

In redpanda-data/docs#937, we introduce a new quickstart that requires users to download multiple files as attachments. To make the UX as streamlined as possible, we want to allow users to download and extract the files in a single archive. Allowing writers to define a group of attachments to use to build an archive reduces manual effort and ensures consistent packaging of related resources.

Benefits

• Efficiency: Automatically creates compressed archives, saving time and minimizing errors.
• Flexibility: Configurable file patterns and replacement rules allow precise control over which attachments are archived and how their content is modified.
• Organization: Prevents archive overwriting using unique naming conventions, ensuring multiple archives coexist.

Configuration Example

antora:
  extensions:
    - require: '../docs-extensions-and-macros/extensions/archive-attachments.js'
      data:
        archives:
           - component: 'ROOT'
              output_archive: 'redpanda-quickstart.tar.gz'
              file_patterns:
                - '**/test-resources/**/docker-compose/**'

Tests

https://deploy-preview-90--docs-extensions-and-macros.netlify.app/preview/test/#attachments

Related PRs

Because this is a breaking change and we have an automation that auto-upgrades the package using latest, we need to merge these PRs in before we release this new major version of the extension to avoid auto-upgrading to this major version:

• Specify a valid semver range for extensions package docs#944
• Specify a valid semver range for extensions package cloud-docs#169
• Specify a valid semver range for extensions package rp-connect-docs#141

[netlify]

✅ Deploy Preview for docs-extensions-and-macros ready!

Name	Link
🔨 Latest commit	5f51917
🔍 Latest deploy log	https://app.netlify.com/sites/docs-extensions-and-macros/deploys/678129ecbb3a380008b8aeef
😎 Deploy Preview	https://deploy-preview-90--docs-extensions-and-macros.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[Deflaimun]

should this have async?

[JakeSCahill]

It's not needed but because it returns a promise, marking it as async makes it more explicit 😄

[Deflaimun]

should this try-catch the error generated in the function?

[Deflaimun]

if const, consider creating outside of the for-loop and define at the start of the script

[Deflaimun]

use the variable instead

[Deflaimun]

Really good new feature. New quickstart is looking 🔥

[JakeSCahill]

Thanks @Deflaimun ! I also implemented the fs.mkdtempSync() function that you mentioned and it works great.

[Deflaimun]

this looks really good. thanks for implementing the changes