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:

```date-calc
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`)

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:**

```date-calc
type: birthday
birthday: 1992-08-16
```

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

### Countdown (`countdown` or `until`)

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:**

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

### Since (`since`)

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:**

```date-calc
type: since
since: 2024-12-20
```

### Difference (`diff`)

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:**

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

```date-calc
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:**

```date-calc
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`
- `countdown` = `until`
- `diff` = `difference`

## Custom Styling

Target these CSS classes in your snippets:

```css
/* 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