date-calculator/README.md

Date Calculator

An Obsidian plugin that adds dynamic date calculations to your notes using date-calc fenced code blocks and inline code.

Features

Fenced Code Blocks

Add date-calc code blocks to your notes for rich date calculations:

type: birthday
birthday: 1992-08-16

Inline Code

Use inline code for quick calculations: date-calc: birthday=1992-08-16

Rendering modes: Inline code and fenced blocks both render in Reading view and Live Preview mode. In Source mode, you'll see the literal date-calc: code until you switch to Reading view or Live Preview.

Supported Calculation Types

Birthday (birthday, bday, age)

Calculates age and time until next birthday.

Fields:

• birthday (or birthdate, date): Birth date
• label (optional): Full prefix text, used verbatim — include your own punctuation (defaults to Age:)

Frontmatter Support: If not provided in the code block, reads birthday/birthdate from the note's frontmatter. If no label is set, a frontmatter name property personalizes the default label automatically (e.g. name: John → John's age:).

Examples:

type: birthday
birthday: 1992-08-16

type: birthday
birthday: 2000-05-21
label: "John's age:"

Countdown (countdown, until, remaining)

Time remaining until a target date, always measured from now. For a comparison between two fixed dates, use diff instead.

Fields:

• to (or date, until): Target date/time
• label (optional): Full prefix text, used verbatim (e.g. label: "New Year:")

Frontmatter Support: If to isn't provided in the code block, reads to/deadline from the note's frontmatter.

Example:

type: countdown
label: "New Year:"
to: 2025-12-31 23:59

Since (since, elapsed)

Time elapsed since an event (or time until, if the event is in the future) — always measured against now.

Fields:

• since (or from, date): Event date/time

Frontmatter Support: If not provided in the code block, reads since/created from the note's frontmatter.

Example:

type: since
since: 2024-12-20

Difference (diff, difference)

The time difference between two fixed dates — neither has to be "now". For a countdown relative to the present moment, use countdown instead.

Fields:

• from (or start): Start date/time
• to (or end): End date/time

Frontmatter Support: If not provided in the code block, reads from/start and to/end from the note's frontmatter.

Examples:

type: diff
from: 2024-02-29
to: 2025-03-01

type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30

Inline Usage

You can use inline code for quick calculations:

• date-calc: birthday=1992-08-16 → Birthday summary
• date-calc: to=2025-12-31 label="New Year:" → Countdown
• date-calc: since=2024-12-20 → Time since event
• date-calc: from=2025-09-19 to=2025-09-20 → Date difference

Formats: Inline code accepts key=value pairs (birthday=1992-08-16) or a flow-mapping YAML object ({type: birthday, birthday: 1992-08-16}).

Frontmatter Integration: Applies to every type, not just birthday — see each type's "Frontmatter Support" above.

Date Formats

Format	Example	Notes
Date only	2026-12-31	—
Date + time	2026-12-31 23:59	—
ISO 8601	2026-12-31T23:59:00	—
Relative keyword	today, now, tomorrow, yesterday	Resolved at render time
Relative offset	+7d, -3mo, +2w, -1y	Units: d, w, mo, y, h, m (minutes) — always relative to now

All dates use your local timezone. Birthday calculations normalize to midnight to avoid timezone edge cases; today/relative keywords resolve to your local time at render.

Relative dates are most useful with diff, since countdown/since are already anchored to now by default — e.g. type: diff with from: today and to: +30d gives a fixed 30-day window that doesn't need updating.

Configuration Options

Verbose Output

Control output verbosity globally via settings or per-calculation:

Global: Settings → Date Calc → Verbose output

Per-calculation override:

type: countdown
to: 2026-12-31
verbose: true

Inline: date-calc: countdown to=2026-12-31 verbose=true

• verbose: true → "Countdown: 1 year, 2 months, 15 days"
• verbose: false → "1y 2mo 15d"

Hide While Editing

Settings → "Hide result while cursor inside" prevents rendered output from showing while you're editing the code, keeping the raw syntax visible.

Field Reference

Birthday

• birthday / birthdate / date — Birth date (falls back to frontmatter birthday/birthdate)
• label — Full prefix, verbatim (defaults to Age:, or <frontmatter name>'s age: if set)
• verbose — Override output format

Countdown

• to / until / date — Target date/time (falls back to frontmatter to/deadline)
• label — Full prefix, verbatim
• verbose — Override output format

Since

• since / from / date — Event date/time (falls back to frontmatter since/created)
• verbose — Override output format

Diff

• from / start — Start date/time (falls back to frontmatter from/start)
• to / end — End date/time (falls back to frontmatter to/end)
• verbose — Override output format

Type Aliases

For convenience, use these shortcuts:

• birthday = bday = age
• countdown = until = remaining
• since = elapsed
• diff = difference

Custom Styling

Target these CSS classes in your snippets:

/* Fenced block results */
.date-calc-block {
  color: var(--text-accent);
  font-weight: 500;
}

/* Inline code results */
.date-calc-inline {
  background: var(--background-secondary);
  padding: 2px 6px;
  border-radius: 3px;
}

Commands

• Toggle debug — Log decoration activity to console
• Toggle verbose — Switch global verbose mode