diff --git a/README.md b/README.md index 2cdb49e..3e41bd6 100644 --- a/README.md +++ b/README.md @@ -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