olivier/date-calculator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Olivier
2025-09-19 21:16:27 -04:00
parent 9021a11172
commit 08f75a8d8a
1 changed files with 93 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
README.md
View File

@@ -1,73 +1,64 @@
# Date Calc
# Date Calculator
This plugin adds a `date-calc` fenced code block you can embed in your notes to render date calculations.
An Obsidian plugin that adds dynamic date calculations to your notes using `date-calc` fenced code blocks and inline code.
Example (birthday):
## Features
### Fenced Code Blocks
Add `date-calc` code blocks to your notes for rich date calculations:
```date-calc
type: birthday
birthday: 1992-08-16
```
Supported types and fields:
### Inline Code
Use inline code for quick calculations: `date-calc: birthday=1992-08-16`
- birthday
- birthday (or birthdate or date): YYYY-MM-DD
- If not provided in the block/inline config, the plugin will also look for a `birthday` (or `birthdate`) property in the note’s frontmatter.
- Output: Age in years and time until next birthday (days, or months if > 31 days, with half-month rounding)
**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.
- countdown / until
- to (or date or until): target date/time
- from (optional): starting date/time (defaults to now)
- label (optional): prefix label
- Output: Humanized time until target, or how long ago if past
## Supported Calculation Types
- diff
- from (or start): start date/time
- to (or end): end date/time
- Output: Humanized difference between the two dates
### Birthday (`birthday`)
Calculates age and time until next birthday with enhanced personalization features.
- since
- since (or from or date): date/time of the event
- Output: Humanized time since that date (or time until if it’s in the future)
**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:")
Notes:
- Dates are interpreted in your local timezone. For birthdays, calculations use local midnight to avoid timezone inconsistencies.
- YAML inside the code block must be valid. The plugin will show an error if the YAML cannot be parsed.
**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.
More examples:
1) Birthday basics
**Examples:**
```date-calc
type: birthday
name: Alice
birthday: 1992-08-16
gender: female
```
```date-calc
type: birthday
birthday: 2000-05-21
label: "John's age:"
```
Aliases for the date field also work:
### Countdown (`countdown` or `until`)
Shows time remaining until a target date.
```date-calc
type: birthday
birthdate: 2000-05-21
```
2) Countdown to a date (future)
**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
```
3) Until (alias of countdown)
```date-calc
type: until
to: 2030-01-01
```
4) Countdown from a custom start time
```date-calc
type: countdown
label: Sprint ends
@@ -75,221 +66,107 @@ to: 2025-10-15 17:00
from: 2025-10-01 09:00
```
5) Since an event (past)
### 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
```
If the date is in the future, the text will say "In: ..." instead of "Since: ... ago".
### Difference (`diff`)
Calculates the time difference between two specific dates.
6) Difference between two 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
```
7) Use times as well as dates
```date-calc
type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30
```
8) Friendly birthday messages near the day
## Inline Usage
```date-calc
type: birthday
birthday: 1992-08-16
```
You can use inline code for quick calculations:
- If today is the birthday: "Wish them Happy Birthday!"
- If tomorrow is the birthday: "Their birthday is tomorrow!"
- If the birthday is > 31 days away: months are shown, with a 0.5 month added when roughly half a month remains.
- `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
9) Error handling examples
**YAML Format:** Inline code also accepts YAML/inline-map format:
`date-calc: {type: birthday, birthday: 1992-08-16, name: Alice}`
Invalid YAML:
**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:
```date-calc
this: is: not: valid
```
Missing required fields:
Example of missing field:
```date-calc
type: diff
from: 2025-01-01
# missing: to
# Error: missing required "to" field
```
The plugin will show a helpful error message in these cases.
## Live Preview and Rendering
Inline usage:
- You can also use inline code like:
- `\`date-calc: birthday=1992-08-16\`` → renders a birthday summary.
- `\`date-calc: to=2025-12-31 label=NewYear\`` → renders a countdown.
- `\`date-calc: since=2024-12-20\`` → time since.
- `\`date-calc: from=2025-09-19 to=2025-09-20\`` → difference between two dates.
- Inline also accepts YAML/inline-map after the colon, e.g. `\`date-calc: {type: birthday, birthday: 1992-08-16}\``.
- For inline birthday, if no date is given, the note’s frontmatter `birthday`/`birthdate` is used when present.
- **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
Tips:
- You can style the rendered line using the CSS class `date-calc` in your snippet or theme.
- ISO-like date strings (YYYY-MM-DD or YYYY-MM-DD HH:mm) work well and are interpreted in your local timezone.
- For birthdays, calculations are normalized to local midnight to avoid off-by-one day issues due to timezones.
## Troubleshooting Inline Code
# Date Calc
If inline code isn't rendering:
This plugin adds a `date-calc` fenced code block you can embed in your notes to render date calculations.
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
Example (birthday):
The plugin's inline processor runs late in the processing chain to avoid conflicts with other processors.
```date-calc
type: birthday
birthday: 1992-08-16
```
## Styling
Supported types and fields:
You can customize the appearance of date calculations using the CSS class `date-calc` in your snippets or theme.
- birthday
- birthday (or birthdate or date): YYYY-MM-DD
- If not provided in the block/inline config, the plugin will also look for a `birthday` (or `birthdate`) property in the note’s frontmatter.
- Output: Age in years and time until next birthday (days, or months if > 31 days, with half-month rounding)
For inline calculations, use the class `date-calc-inline`.
- countdown / until
- to (or date or until): target date/time
- from (optional): starting date/time (defaults to now)
- label (optional): prefix label
- Output: Humanized time until target, or how long ago if past
## Tips
- diff
- from (or start): start date/time
- to (or end): end date/time
- Output: Humanized difference between the two dates
- since
- since (or from or date): date/time of the event
- Output: Humanized time since that date (or time until if it’s in the future)
Notes:
- Dates are interpreted in your local timezone. For birthdays, calculations use local midnight to avoid timezone inconsistencies.
- YAML inside the code block must be valid. The plugin will show an error if the YAML cannot be parsed.
More examples:
1) Birthday basics
```date-calc
type: birthday
birthday: 2000-05-21
```
Aliases for the date field also work:
```date-calc
type: birthday
birthdate: 2000-05-21
```
2) Countdown to a date (future)
```date-calc
type: countdown
label: New Year
to: 2025-12-31 23:59
```
3) Until (alias of countdown)
```date-calc
type: until
to: 2030-01-01
```
4) Countdown from a custom start time
```date-calc
type: countdown
label: Sprint ends
to: 2025-10-15 17:00
from: 2025-10-01 09:00
```
5) Since an event (past)
```date-calc
type: since
since: 2024-12-20
```
If the date is in the future, the text will say "In: ..." instead of "Since: ... ago".
6) Difference between two dates
```date-calc
type: diff
from: 2024-02-29
to: 2025-03-01
```
7) Use times as well as dates
```date-calc
type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30
```
8) Friendly birthday messages near the day
```date-calc
type: birthday
birthday: 1992-08-16
```
- If today is the birthday: "Wish them Happy Birthday!"
- If tomorrow is the birthday: "Their birthday is tomorrow!"
- If the birthday is > 31 days away: months are shown, with a 0.5 month added when roughly half a month remains.
9) Error handling examples
Invalid YAML:
```date-calc
this: is: not: valid
```
Missing required fields:
```date-calc
type: diff
from: 2025-01-01
# missing: to
```
The plugin will show a helpful error message in these cases.
Inline usage:
- You can also use inline code like:
- `\`date-calc: birthday=1992-08-16\`` → renders a birthday summary.
- `\`date-calc: to=2025-12-31 label=NewYear\`` → renders a countdown.
- `\`date-calc: since=2024-12-20\`` → time since.
- `\`date-calc: from=2025-09-19 to=2025-09-20\`` → difference between two dates.
- Inline also accepts YAML/inline-map after the colon, e.g. `\`date-calc: {type: birthday, birthday: 1992-08-16}\``.
- For inline birthday, if no date is given, the note’s frontmatter `birthday`/`birthdate` is used when present.
Troubleshooting inline rendering:
- Inline replacements only run in Reading view and in Live Preview (rendered sections). In Source mode, you’ll just see the literal inline code.
- Type it exactly with a single pair of backticks, e.g. `\`date-calc:birthday\`` or `\`date-calc: birthday=1992-08-16\`` (no triple backticks).
- If it still shows as literal code, try: toggle the note to Reading view and back, or reload the app, or disable/enable the plugin. The plugin’s inline processor now runs late to avoid conflicts with other processors.
- Inline code inside fenced code blocks is intentionally ignored by the plugin so you can document examples in notes and the README.
Tips:
- You can style the rendered line using the CSS class `date-calc` in your snippet or theme.
- ISO-like date strings (YYYY-MM-DD or YYYY-MM-DD HH:mm) work well and are interpreted in your local timezone.
- For birthdays, calculations are normalized to local midnight to avoid off-by-one day issues due to timezones.
- 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