1. Starting the calendar
Open calendar.html in a web browser. The current week starts roughly in the middle of the visible calendar. Only whole weeks that fit in the window are shown; there is no calendar scrollbar.
The calendar uses the proleptic Gregorian calendar from 1 January 1 through 31 December 4000. This means Gregorian rules are extended backward to dates before the historical introduction of that calendar.
2. Understanding the display
Each row represents one Monday-to-Sunday week. Thick stepped lines mark month boundaries. On the right, these boundaries continue through the ISO and month columns, and January boundaries also continue through the year column. Alternating white and light-grey areas distinguish regular cycles when regular cycles are active. When the subcycle is not seven days, alternating white and light-green areas distinguish subcycles; this tint is combined with regular-cycle shading.
Cycle columns on the left
| Heading | Meaning |
|---|---|
| S Cycle | Super-cycle number. This column appears only when super cycles are active. |
| R Cycle | Regular-cycle number within the super cycle, or from the beginning of the calendar when no super cycle is active. This column appears only when regular cycles are active. |
| Week or Sub | Subcycle number within the regular cycle, within the super cycle when no regular cycle is active, or from the beginning of the calendar when neither is active. The heading is “Week” for seven-day subcycles and “Sub” otherwise. A displayed number is determined by the subcycle containing Monday. |
Date columns on the right
| Heading | Meaning |
|---|---|
| ISO | ISO 8601 week number. |
| Mon | Three-letter month abbreviation. |
| Year | Gregorian year. |
Today is highlighted. Text entries appear beside the day number in their selected colours. If space is limited, text is truncated; point to an entry to see its full text as a tooltip.
4. Calendar settings
Regular Cycle
Select the checkbox to display regular cycles. Enter a positive whole number of weeks. The default is 2 weeks. Turning the checkbox off hides the cycle without forgetting its length. A regular cycle must contain a whole number of subcycles.
Super Cycle
Select the checkbox to display super cycles. Enter a positive whole number of weeks. The default is 720 weeks. When regular and super cycles are both active, the super-cycle length must be a multiple of the regular-cycle length. Without a regular cycle, a super cycle must contain a whole number of subcycles.
Subcycle
Enter a positive whole number of days. The subcycle is always active and defaults to 7 days. All cycles begin at 1 January 1. Existing calendars and files that do not contain this setting are treated as having a seven-day subcycle.
Lines per Calendar Day
Choose a value from 2 through 6. This changes day-cell height and consequently the number of weeks that fit on screen. More lines provide more room for entries but show fewer weeks.
Committing or cancelling a number
- Press Enter or leave the field to apply a value.
- Press Escape to restore the previous value.
Changing the regular-cycle length does not alter existing recurring entries. An entry created “per regular cycle” retains the number of weeks that applied when it was created.
5. Creating and editing entries
- Select a day cell. A dialog opens for that date.
- Type into the New entry field.
- Press Enter or leave the field to commit the text. Press Escape to cancel it.
- After committing the text, choose a colour and recurrence. Green and Single are the defaults.
A day may contain multiple entries. Each existing entry has its own panel in the dialog. Edit its text or options directly; there is no separate Edit button. Press Escape while editing text to restore the previous text.
The dialog header shows the conventional date on the left and its multi-week notation on the right. With the default cycles, this has the form Fri/2:2/287:360/147: weekday; subcycle within regular cycle and the number of subcycles per regular cycle; regular cycle within super cycle and the number of regular cycles per super cycle; and super-cycle number. When optional cycles are off, the notation omits their components. For a non-seven-day subcycle, the first component gives the day position and subcycle length, such as 2:2, instead of a weekday abbreviation.
Select Delete in an entry panel to delete that entry. For a recurring entry, Delete removes the recurrence, not only the occurrence currently being viewed.
There are no separate time-of-day or duration fields. Include such information in the entry text if needed.
6. Recurrence options
| Option | Behavior |
|---|---|
| Single | Occurs only on the selected date. |
| Weekly | Occurs every week on the selected weekday. |
| Per regular cycle | Occurs after the configured number of regular-cycle weeks. The interval is captured when the entry is created. |
| Same day each month | Uses the same day number each month. An entry on the 31st is omitted from shorter months. |
| Same day from the end of each month | Preserves the selected date’s numerical distance from month-end. If that position does not exist in a shorter month, the occurrence is omitted. |
| Nth weekday each month | Uses the same ordinal weekday occurrence, such as the third Tuesday. A fifth weekday is omitted from months that contain only four. |
| Nth-last weekday each month | Uses the same reverse ordinal weekday occurrence, such as the second-last Friday. |
| Yearly | Uses the same month and day each year. For example, 29 February is omitted in non-leap years. |
If a per-regular-cycle entry was created under a different regular-cycle length, its selected recurrence is shown as X weeks. Choosing another recurrence removes that historical option.
7. Extending and truncating recurrence
Recurring entries have two range controls:
- Extend back: include earlier occurrences. This is off by default for a new recurrence.
- Extend forward: include later occurrences. This is on by default.
Extensions are initially indefinite. At an interior occurrence, both controls are on. At the first occurrence, only Extend forward is on; at the last occurrence, only Extend back is on.
To truncate a recurrence, open an occurrence that should become the first or last and turn off extension in the unwanted direction. Turning off both directions converts the occurrence to a Single entry.
8. Entry-name and overlap rules
For overlap checking, entry text is compared without regard to capitalization, punctuation, or whitespace. For example, Dance Lesson
and dance-lesson
are treated as the same name.
- Entries with different names may occur on the same date.
- Entries with the same effective name are allowed when their applicable dates do not overlap.
- Entries with the same effective name and different occurrence rules may not touch the same date.
The calendar checks this rule during creation, editing, recurrence extension, loading, and merging. An invalid operation is rejected with an explanatory message.
9. Automatic browser persistence
Settings and calendar entries are saved automatically in the browser’s IndexedDB storage. The viewing position is not saved.
Browser storage belongs to that browser and local page origin. Opening the calendar in a different browser, browser profile, or origin may show a separate calendar. Clearing browser data may erase IndexedDB data.
Use Save regularly to create a separate file backup.
10. Save, Load, Merge, and Clear
Save
Writes all settings and entries to a Cycle Calendar JSON file. The most recently used Save or Load filename and, where the browser permits, its location become the shared defaults for future Save and Load operations.
Load
Replaces the current stored settings and entries with the selected file. Loading is equivalent to opening the file in a fresh calendar. The selected file becomes the shared Save/Load default.
Merge
Combines entries from a selected file with current entries and uses the selected file’s settings. Merge does not use or change the shared Save/Load location. Exact duplicate entries are retained only once. If same-named entries conflict on a date, the entire merge is rejected.
Clear
After confirmation, removes Cycle Calendar data from IndexedDB and restores default settings. Clear does not erase any file previously saved to disk.
An ordinary web page cannot supply a raw local path to a browser file picker. Directory recall depends on browser-managed file handles and picker history. If the browser does not preserve that permission, you may have to navigate to the directory again.
Synchronising between devices
You can use a cloud-synchronised local folder, such as one provided by OneDrive, Dropbox, Google Drive, iCloud Drive, or a similar service, to transfer a saved calendar file between devices. Save the file in that folder, allow the cloud service to synchronise it, and then load it into Cycle Calendar on the other device. Each browser or device may initially require you to locate the file through its file picker.
The cloud service synchronises the file; Cycle Calendar does not continuously synchronise changes. Save and load deliberately, and avoid editing separate copies on different devices before loading the latest version.
11. Date range and browser limitations
- Supported dates are approximately years 1 through 4000.
- Persistence is not shared automatically between browsers.
- Private-browsing modes may restrict or discard IndexedDB data.
- File-picker features vary by browser. Fallback download and upload controls cannot reliably remember a directory.
- Very long text may be truncated in the calendar display, but the full text remains available in the entry dialog.
12. Troubleshooting
| Problem | What to check |
|---|---|
| A cycle setting is rejected. | Use positive whole numbers. A regular cycle must contain whole subcycles; a super cycle must contain whole regular cycles, or whole subcycles when no regular cycle is active. |
| An entry is rejected. | Look for another entry with equivalent text whose applicable dates overlap. |
| A monthly or yearly occurrence is missing. | The required day, Nth weekday, or reverse position may not exist in that month or year. This is expected. |
| A recurrence shows “X weeks.” | It was created using a different regular-cycle length and has retained its original interval. |
| Data is missing in another browser. | IndexedDB data is browser-specific. Load a saved file to transfer the calendar. |
| The file picker opens in an unexpected directory. | The browser may not have retained the prior file handle. Navigate manually; the page cannot reconstruct access from a Windows path string. |
| The calendar shows fewer weeks. | A larger Lines per Calendar Day setting or a smaller browser window reduces the number of whole weeks that fit. |