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.


## Todo
- [ ] Make everything work not only in Live Preview, but Reading also.
- [ ] Add custom language (default to Obsidian language, overridable)


## 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`

**Note about Live Preview**: Inline code works in both Reading view and Live Preview mode. In Live Preview, the result appears after the inline code (e.g., `date-calc: birthday=1992-08-16` → Age: 32 years old...). However, inline code does **not** work for live-preview in Source mode - you'll see the literal code until you switch to Reading view or Live Preview mode.

## Supported Calculation Types

### Birthday (`birthday`)

Calculates age and time until next birthday with enhanced personalization features.

**Fields:**

- `birthday` (or `birthdate`, `date`): Birth date in YYYY-MM-DD format
- `label` (optional): Custom label (defaults to "Age:")

**Frontmatter Support:** If not provided in the code block, the plugin will look for `birthday`/`birthdate`, and `name` properties in the note's frontmatter.

**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`)

Shows time remaining until a target date.

**Fields:**

- `to` (or `date`, `until`): Target date/time
- `from` (optional): Starting date/time (defaults to now)
- `label` (optional): Prefix label for the output

**Examples:**

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

```date-calc
type: countdown
label: Sprint ends
to: 2025-10-15 17:00
from: 2025-10-01 09:00
```


### Since (`since`)

Shows time elapsed since an event (or time until if the event is in the future).

**Fields:**

- `since` (or `from`, `date`): Event date/time

**Example:**

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


### Difference (`diff`)

Calculates the time difference between two specific dates.

**Fields:**

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

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

**YAML Format:** Inline code also accepts YAML/inline-map format:
`date-calc: {type: birthday, birthday: 1992-08-16}`

**Frontmatter Integration:** For inline birthday calculations, if no date is provided, the plugin will use the note's frontmatter `birthday`/`birthdate` property.

## Date Formats

- **Timezone:** All calculations use your local timezone
- **Birthday Calculations:** Normalized to local midnight to avoid timezone inconsistencies

## 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.

## Date Formats

| Format      | Example               | Use Case              |
| :---------- | :-------------------- | :-------------------- |
| Date only   | `2026-12-31`          | Birthdays, countdowns |
| Date + time | `2026-12-31 23:59`    | Precise countdowns    |
| ISO 8601    | `2026-12-31T23:59:00` | Also supported        |

All dates use your local timezone. Birthday calculations normalize to midnight to avoid timezone edge cases.

## Field Reference

### Birthday

- `birthday` / `birthdate` / `date` — Birth date 
- `verbose` — Override output format (optional)


### Countdown

- `to` / `until` / `date` — Target date/time
- `from` — Start date (defaults to now)
- `label` — Custom prefix
- `verbose` — Override output format


### Since

- `since` / `from` / `date` — Event date/time
- `verbose` — Override output format


### Diff

- `from` / `start` — Start date/time
- `to` / `end` — End date/time
- `verbose` — Override output format


## Type Aliases

For convenience, use these shortcuts:

- `birthday` = `bday`
- `countdown` = `until`
- `diff` = `difference`


## Inline Syntax Formats

All three formats work:

**Key=value:** ```date-calc: birthday=1992-08-16```
**YAML-like:** ```date-calc: type: birthday, birthday: 1992-08-16```
**Compact:** ```date-calc: {type: birthday, birthday: 1992-08-16}```




## 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