Implement a page for downloading .ics files

[arkid15r]

Is your feature request related to a problem? Please describe.
Currently, .ics files are planned to be distributed in the repository for different countries, but there is no dedicated portal for users to easily review and download these files. While Issue #3163 focuses on generation of .ics files, users would benefit from an intuitive interface to download them and preview their content, especially for non-technical audiences or mass adoption cases.

Describe the solution you'd like
Implement a GitHub Pages-based portal as part of the repository that allows users to download .ics files for different countries/regions. This portal should:

• Provide a modern, user-friendly interface (good UX/UI)
• Allow filtering and selecting country/region/category/year -- let's discuss
• Link or directly serve up-to-date .ics files (generated via bot or workflows)
• Optionally, allow preview before download
• Be implemented using modern static site generators and JavaScript/CSS libraries if needed
• Ensure responsive design and accessibility

The implementation includes two main tasks:

1. Automate the generation of .ics files as discussed in Distribute .ics files in the repo #3163, and
2. Develop the frontend (portal) and integrate it with the generation output, ensuring an easy and pleasant download/preview experience for users via GitHub Pages.
3. Automate it as part of CI/CD

Additional context
Reference for .ics files distribution:

• https://github.com/commenthol/date-holidays/
• Example .ics files: https://github.com/FossifyOrg/Calendar/blob/main/app/src/main/assets/holidays/SE/other.ics, https://github.com/FossifyOrg/Calendar/blob/main/app/src/main/assets/holidays/SE/public.ics
• Issue Distribute .ics files in the repo #3163: Distribute .ics files in the repo #3163

This proposal aims to enhance access and usability of holiday calendar data for a global user base, supporting both automation and frontend web development best practices.

// drafted w/ copilot

[pareshjoshij]

I started analyzing the requirements and built a basic prototype to test the concept. I'm using Alpine.js inside docs/downloads.md to keep it lightweight and integrated with the current theme.

Does this simple UI approach align with our vision, or should I try a different design?

[KJhellico]

Hmm, the idea of adding this to the documentation seems very interesting. 👍

[arkid15r]

@pareshjoshij good thinking 👍

FYI -- we need to make it available on per category basis. I believe something like a multi-select for categories with public selected by default would be great. Optionally, add "select all" and "invert selection" controls for entity categories selection.

[pareshjoshij]

@arkid15r , @KJhellico Thanks for the feedback! ❤️

I will add the multi-select options (with "Select All" and "Invert") to match that requirement. I've been looking at the reference site you mentioned, and I have a plan to make our implementation just as fast.

Two questions before I start:

• Year Range: How many years should we support initially? For example, should we generate files from 2010 to 2026? I'll make sure the script is dynamic so it automatically adds future years (2027, 2028, etc.) as time goes on.

• Performance & JSON: To keep the UI preview instant, I propose a dual-file approach:

  • The workflow generates the .ics file for the actual download.
  • It also generates a lightweight .json file containing just the data needed for the table preview.
  • The frontend will fetch the JSON for the display (much faster than parsing ICS in the browser) and link to the ICS for the download.

Does this approach sound good to you? If so, I'm ready to start working on it!

[KJhellico]

should we generate files from 2010 to 2026?

I think, something like 2011-2030, or 2015-2030, or 2020-2030...

lightweight .json file

Like snapshots now?

Also,

1. Consider that there will be need to somehow merge .ics files of selected (in multi-selection) categories.
2. Requires selection of language and subdivision (available in selected entity).

[pareshjoshij]

I think, something like 2011-2030, or 2015-2030, or 2020-2030...

2015–2030 is a solid range. It covers enough history and future planning without bloating the repo

Like snapshots now?

For Preview separate, lightweight .json file for each Country or Financial entity per year (e.g., US_2025.json).

1. Consider that there will be need to somehow merge .ics files of selected (in multi-selection) categories.

Since this is a static site, we should handle merging client-side. The browser (JS) can simply filter the JSON and generate the combined .ics blob on the fly.

[KJhellico]

lightweight .json file for each Country or Financial entity per year

I meant the file structure as it is now in snapshots.

The browser (JS) can simply filter the JSON and generate the combined .ics blob on the fly.

Yes, that's what I meant.

[KJhellico]

Note: currently we get 4960 files per year (with all subdivisions/languages/categories). ;)

[pareshjoshij]

I meant the file structure as it is now in snapshots.

Yes kind of snapshots

[davidhedlund]

I just submitted a related feature request:

• [Feature request] vacanza-holidays.py to generate calendars for any country, year, etc #3189

[davidhedlund]

I started analyzing the requirements and built a basic prototype to test the concept. I'm using Alpine.js inside docs/downloads.md to keep it lightweight and integrated with the current theme.

Does this simple UI approach align with our vision, or should I try a different design?

Thank you very much for this contribution!