DOC-798 Add extension to calculate end-of-life date

[JakeSCahill]

This PR introduces an extension for managing the lifecycle of documentation versions. The extension calculates and attaches metadata about the end-of-life (EoL) status of pages based on the page-release-date attribute of the component version and customizable configuration settings for the extension. The resulting metadata can be used in UI templates to display banners or messages about nearing or past EoL statuses. See redpanda-data/docs-ui#242

Adds the following attributes to pages:

• page-is-nearing-eol: Indicates if the page is within the warning period before EoL. Calculated using (page-release-date + supported_months) - warning_weeks in https://github.com/redpanda-data/docs-extensions-and-macros/pull/92/files#diff-593ab60cae40c90a344cd9b8470d5b0cf45e558aee684093cbb7c92151d66589.
• page-is-past-eol: Indicates if the page has passed its EoL. Calculated using today > (page-release-date + supported_months) in https://github.com/redpanda-data/docs-extensions-and-macros/pull/92/files#diff-593ab60cae40c90a344cd9b8470d5b0cf45e558aee684093cbb7c92151d66589.
• page-eol-date: The calculated EoL date in a human-readable format, such as "March 1, 2025". See https://github.com/redpanda-data/docs-extensions-and-macros/pull/92/files#diff-593ab60cae40c90a344cd9b8470d5b0cf45e558aee684093cbb7c92151d66589
• page-eol-doc: A URL to the policy for supported versions. Defined in the extension config.
• page-upgrade-doc: An Antora resource ID to a doc containing upgrade instructions. Defined in the extension config.

Usage

1. In each antora.yml for versioned components, add the release date in the format YYYY-MM-DD.
   For example:

   name: preview
   title: Extensions and Macros Preview
   version: ~
   start_page: preview:ROOT:test.adoc
   nav:
   - modules/ROOT/nav.adoc
   asciidoc:
     attributes:
       page-release-date: 2024-03-01

2. Configure the extension in the playbook, specifying the supported_months (how long the version is supported) and warning_weeks (how long before the EoL date to display the banner). Both of these configs have defaults of 12 and 6, respectively.

antora:
  extensions:
    - require: '@redpanda-data/docs-extensions-and-macros/extensions/end-of-life'
      data:
        eol_settings:
          - component: 'ROOT'
            supported_months: 18
            warning_weeks: 8
            eol_doc: https://support.redpanda.com/hc/en-us/articles/20617574366743-Redpanda-Supported-Versions
            upgrade_doc: ROOT:upgrade:index.adoc

Example attributes for a page whose doc version with publish-date 2024-03-01:

page-is-nearing-eol: false
page-is-past-eol: true
page-eol-date: 'March 1, 2025'
page-eol-doc: 'https://support.redpanda.com/hc/en-us/articles/20617574366743-Redpanda-Supported-Versions'
page-upgrade-doc: 'ROOT:upgrade:index.adoc'

Testing

Edit the extension configuration locally in local-antora-playbook.yml and check the output here: https://deploy-preview-92--docs-extensions-and-macros.netlify.app/preview/test/#end-of-life-attributes

[netlify]

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

Name	Link
🔨 Latest commit	4179a52
🔍 Latest deploy log	https://app.netlify.com/sites/docs-extensions-and-macros/deploys/67878b339e1e4400081ac904
😎 Deploy Preview	https://deploy-preview-92--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]

Consider using ISO 8601 dates to avoid problems with timezones.

Example date in ISO 8601 "2025-01-14T10:00:00Z" -> 10:00 UTC

[Deflaimun]

Using this method without setting a timezone can lead to discrepancies depending on where the server is located.

Consider doing something like this to make sure that it's always executed in the same timezone.

const timeZone = 'UTC'; 

const now = new Date();
const formattedDate = new Intl.DateTimeFormat('en-US', {
  timeZone,
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
}).format(now);

[Deflaimun]

You can possibly extend this to announcement banners and how long a beta is up too

and be mindful of timezones. Either force it use UTC or bay area timezone ("America/Los_Angeles")