Text Enrichers

Calendaria adds inline enrichers that work anywhere Foundry renders rich text: journal pages, chat messages, item descriptions, note content.

An enricher is the cal. prefix plus a type. Most types take optional parameters, a custom label, or a cross-calendar query.

[[cal.<type>]]                 → basic
[[cal.<type> <params>]]        → with parameters
[[cal.<type>]]{Custom Label}   → custom display label
[[cal.<type> cal=<id>]]        → cross-calendar query
[[cal.<type> date="<day> <month> <year>"]]  → pinned to a date
[[cal.<type> zone=<id>]]       → read a named climate zone

Tip

A custom label replaces the display text. The tooltip still shows the real value, and the enricher stops updating live.

---

Inserting enrichers from the editor

Any ProseMirror editor has an insert menu with a Calendaria group. Journal pages and note content both use one.

The group splits into submenus: Actions, Calendar, Composite, Date & Time, Moon, Notes, Sun & Daylight, Time Math, and Weather. Submenus and the entries inside them are both sorted alphabetically by label. Picking an entry drops its [[cal.<type>]] markup at the cursor.

Action entries that need arguments insert with bracket placeholders you replace. Jump to Date inserts [[cal.jumptodate [DAY] [MONTH] [YEAR]]].

Several entries in the other submenus insert with a worked sample value instead. Overwrite the sample with the date, note name, or format string you want.

---

Choosing a date

Every enricher that reports something about a date resolves that date in a fixed order.

1. An explicit date you write into the enricher.
2. The start date of the note the enricher sits in.
3. The current calendar date.

Writing now skips the first two steps and reports the current date.

[[cal.weather now]]

Write an explicit date with the date argument. The value is a day, a month, and a year separated by spaces, wrapped in quotes. The month accepts a number, a month name, or a month abbreviation.

[[cal.sunrise date="5 Mirtul 1492"]]
[[cal.weather date="5 3 1492"]]

Enrichers whose first positional slot is free also take the date positionally.

[[cal.weekday 5 3 1492]]
[[cal.temperature 5 Mirtul 1492]]

The moon, nextfullmoon, eclipse, nexteclipse, forecast, format, and peek enrichers already read their first positional slot as something else, so they take a date only through date.

[[cal.moon 1 date="5 3 1492"]]
[[cal.forecast 5 date="5 3 1492"]]

The date, time, and notes enrichers sit outside this order. time always reports the current time. date and notes read a date only from their positional slot, so date, now, and a host note’s start date have no effect on them.

Caution

A bare enricher such as [[cal.weather]] inside a note that has a start date reports that note’s date. Add now to pull it back to the current date.

A pinned enricher stops updating as time advances. It renders once and holds the value for the date you named.

A date whose day does not exist in that month renders as Date not recognized. So does [[cal.date now]], because date reads now as a date and fails to parse it.

---

Reading another climate zone

Sun, season, and weather enrichers read the climate zone of the active scene. Write the zone argument to name a different zone instead.

[[cal.weather zone=desert]]
[[cal.sunrise date="5 3 1492" zone=highlands]]

Without zone, a pinned weather lookup falls back to the first zone that recorded that date when the scene’s zone has no record. Write zone when you need the reading to come from one zone or nothing at all.

A weather lookup pinned to both a date and a zone does not fall back to another zone’s record.

---

Date and time

time always reports the current time. date reads a date only from its positional slot. The rest accept a date positionally or through date. See Choosing a date.

date

Display a date. Click to navigate the calendar to that date.

[[cal.date]]                 → 5 Shadowmoon, 1499
[[cal.date 15 Mirtul 1492]]  → 15 Mirtul, 1492
[[cal.date 15 5 1492]]       → 15 Mirtul, 1492
[[cal.date format=dateFull]] → Mercday, 5 Shadowmoon 1499
[[cal.date approx=true]]     → Late Winter
[[cal.date time=true]]       → 5 Shadowmoon 1499, 14:30
[[cal.date format="{the }Do{ day of }MMMM"]] → the 5th day of Shadowmoon

Parameter	Type	Description
positional	day month year	Specific date (month name or index). Omit for current date
format	string	Format preset or token string
approx	boolean	Approximate date description
time	boolean	Include time

Custom format strings inside an enricher must wrap literal text in {...} rather than [...], because the [[...]] delimiters collide with [literal]. Both forms work in the Display Format editor.

---

time

Display the current time.

[[cal.time]]              → 14:30
[[cal.time 12h=true]]     → 2:30 PM
[[cal.time approx=true]]  → Afternoon

Parameter	Type	Description
12h	boolean	12-hour format
approx	boolean	Approximate time of day

---

weekday

[[cal.weekday]] → Mercday

---

season

[[cal.season]] → Spring

---

era

[[cal.era]] → Second Age

---

cycle

[[cal.cycle]] → Temporis

---

festival

Click to open the festival note if one exists.

[[cal.festival]] → Midsummer

---

restday

[[cal.restday]] → Work Day

---

Time math

countdown

Days until a target date. Click to navigate to the target.

[[cal.countdown 1 Mirtul 1500]] → in 45 days
[[cal.countdown 1 6 1500]]      → in 45 days

---

countup / elapsed

Days since a target date, or days until when to= points to a future date. Click to navigate to the target. The tooltip shows days until a future static target and days since otherwise.

[[cal.countup 1 Mirtul 1490]]                                               → 730 days
[[cal.countup 1 Mirtul 1490 relative=true]]                                 → in 2 years
[[cal.countup 1 Mirtul 1490 relative=true simple=true]]                     → 2
[[cal.countup 1 Mirtul 1490 to="1 Mirtul 1492"]]                           → 730 days
[[cal.countup 1 Mirtul 1490 to="1 Mirtul 1492" relative=true simple=true]]  → 2
[[cal.countup 1 Mirtul 1490 to="event"]]                                    → 730 days
[[cal.countup 1 Mirtul 1490 to="High Harvestide"]]                          → 730 days
[[cal.elapsed 1 Mirtul 1490]]                                               → 730 days

Parameter	Type	Description
relative	boolean	Human-readable relative text (years/months/weeks)
simple	boolean	Return only the numeric count
to	string	End date (to="1 Mirtul 1492"), to="event" for the host note’s start date, or a note name (to="High Harvestide")

---

between

Distance between two dates.

[[cal.between 1 1 1490 to 1 6 1490]]             → 150 days
[[cal.between 1 1 1490 to 1 6 1490 unit=months]] → 5 months

Parameter	Type	Description
unit	string	months for month count

---

timeuntil

Time until a target event.

[[cal.timeuntil sunrise]]           → 3h 20m
[[cal.timeuntil sunset]]            → 8h 15m
[[cal.timeuntil midnight]]          → 9h 30m
[[cal.timeuntil midday]]            → 2h 10m
[[cal.timeuntil sunset hours=true]] → 8h 15m

Parameter	Type	Description
hours	boolean	Compact “Xh Ym” format

Targets: sunrise, sunset, midnight, midday

---

datemath

Date arithmetic from the current date. Click to navigate to the result.

[[cal.datemath +30d]]    → 6 Thawmoon, 1500
[[cal.datemath +2m -5d]] → 1 Shadowmoon, 1499
[[cal.datemath +1y]]     → 5 Shadowmoon, 1500

Units: d (days), m (months), y (years)

---

Calendar

These accept a date positionally or through date. See Choosing a date.

calname

[[cal.calname]] → Forgotten Realms

---

month

[[cal.month]] → Shadowmoon

---

year

[[cal.year]] → 1499

---

dayofyear

[[cal.dayofyear]] → 287

---

yearprogress

Renders a progress bar.

[[cal.yearprogress]] → 79% (progress bar)

---

leapyear

[[cal.leapyear]] → Not a Leap Year

---

intercalary

[[cal.intercalary]] → Standard

---

daysinyear

[[cal.daysinyear]] → 365

---

Sun and daylight

These accept a date and a zone. See Choosing a date.

sunrise / sunset

[[cal.sunrise]] → 06:30
[[cal.sunset]]  → 18:45
[[cal.sunrise 5 3 1492]]
[[cal.sunset date="5 3 1492"]]

---

daylight

[[cal.daylight]] → 12.3h

---

isdaytime

[[cal.isdaytime]] → Daytime

---

dayprogress / nightprogress

[[cal.dayprogress]]   → 65%
[[cal.nightprogress]] → 23%

---

untilsunrise / untilsunset

[[cal.untilsunrise]] → 5h 30m
[[cal.untilsunset]]  → 2h 15m

---

Moon

moon

Display moon phase info.

[[cal.moon]]               → Waxing Crescent (with icon)
[[cal.moon 1]]             → Full Moon (second moon)
[[cal.moon icon=true]]     → (icon only)
[[cal.moon position=true]] → 45%
[[cal.moon cycleday=true]] → 12
[[cal.moon isfull=true]]   → Not Full Moon
[[cal.moon 1 date="5 3 1492"]]

The moon index holds the positional slot, so the date must use date.

Parameter	Type	Description
positional	number	Moon index (0-based)
date	string	Date to report, as day month year
icon	boolean	Icon only
position	boolean	Cycle position %
cycleday	boolean	Day in cycle
isfull	boolean	Full moon check

---

moons

[[cal.moons]] → Selune: Full Moon, Tears: Waning
[[cal.moons 5 3 1492]]

---

nextfullmoon

Click the date mode to navigate to that date.

[[cal.nextfullmoon]]           → 22 Shadowmoon, 1499
[[cal.nextfullmoon countdown]] → in 8 days
[[cal.nextfullmoon 1]]         → 15 Thawmoon, 1499

---

convergence

Click to navigate. Requires two or more moons.

[[cal.convergence]] → 15 Thawmoon, 1501
[[cal.convergence 5 3 1492]]

---

Eclipse

eclipse

Current eclipse status for a moon. Requires eclipses enabled in the Calendar Editor moon settings.

[[cal.eclipse]]   → Total Solar Eclipse
[[cal.eclipse 1]] → Partial Lunar Eclipse

Parameter	Type	Description
positional	number	Moon index (0-based)
date	string	Date to evaluate, as day month year

Eclipse types: Total Solar, Partial Solar, Annular Solar, Total Lunar, Partial Lunar, Penumbral Lunar. Returns “No Eclipse” when none is occurring.

---

nexteclipse

Date of the next eclipse. Click the date mode to navigate to that date.

[[cal.nexteclipse]]             → 22 Shadowmoon, 1499
[[cal.nexteclipse countdown]]   → in 12 days
[[cal.nexteclipse 1]]           → 8 Thawmoon, 1500
[[cal.nexteclipse 1 countdown]] → in 45 days

Parameter	Type	Description
positional	number	Moon index (0-based)
positional	string	countdown for relative days
date	string	Date to evaluate, as day month year

---

Weather

A weather enricher pinned to a past date reads its value from the recorded weather history. A date with no recorded weather renders a muted badge naming that date rather than an error. See Weather History.

weather

[[cal.weather]] → Clear Skies (with icon)
[[cal.weather date="5 3 1492"]]

---

temperature

[[cal.temperature]] → 72F
[[cal.temperature 5 3 1492]]

---

wind

[[cal.wind]] → Moderate SSE
[[cal.wind 5 3 1492]]

---

precipitation

[[cal.precipitation]] → None
[[cal.precipitation 5 3 1492]]

---

weathericon

[[cal.weathericon]] → (icon only)
[[cal.weathericon date="5 3 1492"]]

---

zone

[[cal.zone]] → Temperate

---

forecast

Each line pairs a short date with the weather, the temperature, and the wind. When the first day of the forecast is today, that line shows the weather currently in effect rather than the planned entry.

[[cal.forecast]]   → 3-day forecast
[[cal.forecast 5]] → 5-day forecast
[[cal.forecast 5 date="5 3 1492"]]

Parameter	Type	Description
positional	number	Days to forecast (default 3)
date	string	Date to forecast from, as day month year
zone	string	Climate zone id to forecast for

---

Notes

event

Click to open the note. A search term matching no note renders dimmed and unclickable rather than as an error.

[[cal.event The Council Meeting]] → The Council Meeting

---

notes

[[cal.notes]]                        → Council Meeting, Dragon Attack
[[cal.notes 15 5 1492]]              → Session Recap
[[cal.notes count=true]]             → 3 notes
[[cal.notes count=true scope=month]] → 12 notes
[[cal.notes links=true]]             → Council Meeting, Dragon Attack
[[cal.notes 1 5 1492 to 7 5 1492 links=true]] → Session Recap, Council Meeting

Parameter	Type	Description
count	boolean	Show count instead of names
scope	string	month for monthly count
links	boolean	Render each note as a clickable link

In links mode a two-date range is accepted and each matching day is labeled. Nothing is rendered when no notes match.

---

next

Click the date mode to open the note.

[[cal.next Council Meeting]]           → 22 Mirtul, 1492
[[cal.next Council Meeting countdown]] → in 7 days

---

category

Uses the category’s icon.

[[cal.category Holidays]] → Midsummer, Shieldmeet

---

chronicle

Click to open the Chronicle View locked to the date range. Infinite scroll is disabled at the boundaries and the Today button is hidden.

[[cal.chronicle 1 10 1492 to 31 10 1492]] → 1 Shadowmoon, 1492 - 31 Shadowmoon, 1492
[[cal.chronicle 1 1 1500 to 14 1 1500]]{The Founding Week} → The Founding Week

Parameter	Type	Description
cal	string	Calendar ID to scope notes/weather to (optional)
categories	string	Comma-separated preset IDs applied as a one-shot Chronicle category filter; does not modify the persisted user filter (optional)

---

Composite

summary

Click to navigate to the resolved date.

[[cal.summary]] → 5 Shadowmoon, 1499 · Clear · Waxing
[[cal.summary date="5 3 1492"]]

---

almanac

The block lists the full date, the season, the weather and temperature, the wind, the first moon’s phase, and sunrise with sunset. A line is omitted when the calendar has no data for it.

[[cal.almanac]] → (multi-line block)
[[cal.almanac date="5 3 1492"]]

---

format

See Format Tokens.

[[cal.format EEEE, Do MMMM Y]] → Mercday, 5th Shadowmoon 1499
[[cal.format EEEE, Do MMMM Y date="5 3 1492"]]

The date, zone, and cal arguments are stripped out before the rest is read as the format string.

---

compare

Click to navigate to the target.

[[cal.compare 1 1 1490]] → in 9 years (3285 days)

---

peek

Click to navigate to the result.

[[cal.peek +7d]] → 12 Shadowmoon, 1499
[[cal.peek +1m]] → 5 Thawmoon, 1499
[[cal.peek +7d date="5 3 1492"]]

The date math applies relative to the pinned date.

---

Actions

Clickable buttons that change the calendar. Time actions need the Change Date/Time permission and weather actions need Change Weather. See Permissions.

advancetotime

Advance the clock to the next HH:MM.

[[cal.advancetotime 06:30]]                  → advance forward to 06:30
[[cal.advancetotime 06:30 direction=nearest]] → snap to the closer side of midnight

Parameter	Type	Description
positional	string	Target HH:MM
direction	string	nearest to snap to the closer side of midnight

---

advanceinterval

Advance time by a composite delta.

[[cal.advanceinterval hour=2 minute=30]] → +2h 30m
[[cal.advanceinterval day=1 hour=6]]     → +1d 6h

A negative count rewinds instead. [[cal.advanceinterval hour=-2]] moves the clock back two hours.

Unit	Suffix
second	s
round	r
minute	m
hour	h
day	d
week	w
month	mo
season	sea
year	y

---

advancetopreset

Advance to the next named time-of-day.

[[cal.advancetopreset sunrise]]
[[cal.advancetopreset sunset]]

Targets: sunrise, midday, noon, sunset, midnight.

---

settime

Snap the clock to HH:MM on the current date without changing the day.

[[cal.settime 06:00]]

---

jumptodate

Move the world clock to the given date, preserving the current time of day.

[[cal.jumptodate 15 Mirtul 1492]]
[[cal.jumptodate 15 5 1492]]

---

toggleclock

Toggle the real-time TimeClock on and off.

[[cal.toggleclock]]

---

setweather

Apply a weather preset id.

[[cal.setweather clear]]
[[cal.setweather rain temperature=12 period=morning]]
[[cal.setweather snow allPeriods=true]]

Parameter	Type	Description
positional	string	Preset id
temperature	number	Override temperature
period	string	Intraday period to apply to
zoneId	string	Climate zone id
allPeriods	boolean	Apply to all intraday periods

---

Cross-calendar

Add cal=<id> to query a non-active calendar.

[[cal.date cal=harptos]]     → 15 Mirtul, 1492
[[cal.moon cal=krynn]]       → Full Moon
[[cal.season cal=gregorian]] → Winter

This is read-only. Click navigation still targets the active calendar.