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

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
• name (optional): Person's name for personalized output
• gender (optional): male/m, female/f, or neutral for appropriate pronouns
• label (optional): Custom label (defaults to "Age:")

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

Examples:

type: birthday
name: Alice
birthday: 1992-08-16
gender: female

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:

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

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:

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:

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

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

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

Date Formats

• Dates: YYYY-MM-DD (e.g., 2025-12-31)
• Date + Time: YYYY-MM-DD HH:mm (e.g., 2025-12-31 23:59)
• Timezone: All calculations use your local timezone
• Birthday Calculations: Normalized to local midnight to avoid timezone inconsistencies

Error Handling

The plugin provides helpful error messages for common issues:

• Invalid YAML: Shows parsing error details
• Missing Required Fields: Indicates which fields are needed
• Invalid Dates: Warns about unrecognizable date formats

Example of invalid YAML:

this: is: not: valid

Example of missing field:

type: diff
from: 2025-01-01
# Error: missing required "to" field

Live Preview and Rendering

• Fenced Code Blocks: Work in all view modes (Source, Live Preview, Reading)
• Inline Code: Works in Reading view and Live Preview mode
  • In Live Preview: Shows result after the inline code with an arrow (→)
  • In Source mode: Shows literal code until you switch views
• Code Inside Fenced Blocks: Intentionally ignored to allow documentation examples

Troubleshooting Inline Code

If inline code isn't rendering:

1. Check View Mode: Switch to Reading view or Live Preview mode
2. Syntax: Use single backticks (not triple): date-calc: birthday=1992-08-16
3. Refresh: Try toggling the note view or reloading the app
4. Plugin Status: Disable and re-enable the plugin if needed

The plugin's inline processor runs late in the processing chain to avoid conflicts with other processors.

Styling

You can customize the appearance of date calculations using the CSS class date-calc in your snippets or theme.

For inline calculations, use the class date-calc-inline.

Tips

• Use ISO date format (YYYY-MM-DD) for best compatibility
• Birthday calculations handle leap years and timezone edge cases
• For personalized birthday messages, add name and gender to your note's frontmatter
• The plugin integrates with Obsidian's metadata cache for frontmatter access