maomao233/csv-to-ical

CSV-to-iCal

https://github.com/fantasticmao/csv-to-ical/workflows/ci/badge.svg](https://github.com/fantasticmao/csv-to-ical/actions) https://codecov.io/gh/fantasticmao/csv-to-ical/branch/main/graph/badge.svg](https://codecov.io/gh/fantasticmao/csv-to-ical) https://img.shields.io/badge/docker_hub-released-blue.svg?logo=docker](https://hub.docker.com/r/maomao233/csv-to-ical) !https://img.shields.io/github/go-mod/go-version/fantasticmao/csv-to-ical https://goreportcard.com/badge/github.com/fantasticmao/csv-to-ical](https://goreportcard.com/report/github.com/fantasticmao/csv-to-ical) https://img.shields.io/github/v/release/fantasticmao/csv-to-ical](https://github.com/fantasticmao/csv-to-ical/releases) https://img.shields.io/github/license/fantasticmao/csv-to-ical](https://github.com/fantasticmao/csv-to-ical/blob/main/LICENSE)

README English | 中文

What is this

CSV-to-iCal is a rapidly deployable Web application based on the Go language, used to convert https://datatracker.ietf.org/doc/html/rfc4180 format content into https://datatracker.ietf.org/doc/html/rfc5545 format online subscription links. For example, you can import calendar events from calendar_test.csv into your iOS Calendar / Google Calendar by subscrig to the URL <[]>.

!usage

csv-to-ical.fantasticmao.cn is an out-of-the-box CSV-to-iCal service instance provided for general users, actually running on my HomeLab and exposed to the public network via Cloudflare Tunnel.

CSV-to-iCal currently supports the following features:

• Fully respects user privacy, does not retain any user content, code is 100% open source and transparent
• Supports reading local CSV files, supports reading remote CSV files via HTTP protocol
• Supports Gregorian and Lunar calendar events
• Supports calculating the age for Gregorian birthday events, supports calculating the nominal age for Lunar birthday events
• Supports English (default) and Chinese languages
• Supports recurring events for up to 5 years
• Supports retrospective events for up to 3 years

Download and Install

bash
git clone https://github.com/fantasticmao/csv-to-ical.git
cd csv-to-ical

bash
go build -o csv-to-ical .

bash
go install github.com/fantasticmao/csv-to-ical@latest

bash
docker pull maomao233/csv-to-ical:latest

bash
docker run -d -p 7788:7788 -v /path/to/your/config/:/opt/csv-to-ical/ maomao233/csv-to-ical:latest

Quick Start

yaml
bind-address: 0.0.0.0:7788 # Program listening address and port, default is 0.0.0.0:7788

http-client:
  timeout: 3000 # HTTP client timeout (milliseconds), default is 3000ms
  proxy: ""     # Optional HTTP proxy address, e.g., http://127.0.0.1:7890

csv-providers:
  # 'remote' provider example, used to process remote CSV files
  my-remote-calendar:
    url: "https://raw.githubusercontent.com/fantasticmao/csv-to-ical/main/csv/testdata/calendar_test.csv"
    language: "zh-cn" # Event language, optional "en" (default) or "zh-cn"
    recurCnt: 5       # Maximum number of years for recurring events, default is 3, max 5
    backCnt: 2        # Maximum number of years for retrospective events, default is 1, max 3

  # 'local' provider example, used to process local CSV files
  my-local-calendar:
    file: "/path/to/your/calendar.csv" # Local CSV file path
    language: "en"
    recurCnt: 3
    backCnt: 1

bash
go run main.go

bash
csv-to-ical -d /path/to/your/config

start HTTP server success, bind address: 0.0.0.0:7788

Usage Instructions

CSV File Format

The CSV file format has specific requirements and should contain the following columns:

CSV File Example

For details, please see calendar_test.csv.

Using Remote CSV Files

You can subscribe to a publicly accessible CSV file via the remote interface. For example, if you have a public CSV file link <[***]>, you can use the following URL to access it:

https://<your-csv-to-ical-host>/remote?url=encode(https://example.com/your-calendar.csv)

https://<your-csv-to-ical-host>/remote?base64=encode(base64(your calendar csv content))

• url (or base64): URL encoding of the remote CSV file.
• base64 (or url): URL encoding of the base64-encoded content of the remote CSV file.
• lang (optional): Event language, en (default) or zh-cn.
• recurCnt (optional): Maximum number of years for recurring events, default is 3, max 5.
• backCnt (optional): Maximum number of years for retrospective events, default is 1, max 3.

For example, to subscribe to a Chinese recurring event, repeating for a maximum of five years, and retrospecting for a maximum of two years:

https://<your-csv-to-ical-host>/remote?lang=zh-cn&recurCnt=5&backCnt=2&url=https%3A%2F%2Fexample.com%2Fyour-calendar.csv

Using Local CSV Files

If you want to use local CSV files, you need to configure them via config.yaml. Add an entry in the csv-providers section, specifying the file path.

For example, configure in config.yaml:

yaml
csv-providers:
  my-local-calendar:
    file: "/path/to/your/calendar_example.csv"
    language: "zh-cn"
    recurCnt: 5
    backCnt: 2

Then, you can access it via the following URL:

https://<your-csv-to-ical-host>/local/my-local-calendar

Here, my-local-calendar corresponds to the key name under csv-providers in config.yaml.

Frequently Asked Questions

Q: Why aren't my calendar events displayed?

A: Please check if your CSV file format is correct, especially if the columns Name, Month, Day, Year, CalendarType exist and the data format is correct. Also, check if the file path or url encoding in config.yaml is correct.

Q: How to enable HTTPS?

A: CSV-to-iCal itself does not directly provide HTTPS functionality. It is recommended to configure a reverse proxy (such as Nginx, Caddy, Cloudflare Tunnel, etc.) in front to handle HTTPS.

Q: What do recurCnt and backCnt mean?

A: recurCnt (recurrence count) specifies the maximum number of years for which recurring events will be generated (starting from the current year). backCnt (back count) specifies the maximum number of years for retrospective events (looking back from the current year).

License

CSV-to-iCal https://github.com/fantasticmao/csv-to-ical/blob/main/LICENSE

Copyright (c) 2023 fantasticmao