diff --git a/README.md b/README.md index ee82264..add5a17 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,14 @@ An Obsidian plugin that adds dynamic date calculations to your notes using `date ## Todo -- [x] Make inline work -- [ ] Add a non-verbose birthday type? Just show the age, with decimals, maybe? Like "3.7 years old" -- [ ] +- [ ] 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 @@ -19,7 +19,9 @@ 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. @@ -27,22 +29,21 @@ Use inline code for quick calculations: `date-calc: birthday=1992-08-16` ## 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. +**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 -name: Alice birthday: 1992-08-16 -gender: female ``` ```date-calc @@ -51,15 +52,19 @@ 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 @@ -73,26 +78,34 @@ 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 @@ -103,7 +116,8 @@ to: 2025-03-01 type: diff from: 2025-09-19 08:00 to: 2025-09-19 16:30 -``` +``` + ## Inline Usage @@ -115,65 +129,122 @@ You can use inline code for quick calculations: - `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}` +`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 -- **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 +## Configuration Options -The plugin provides helpful error messages for common issues: +### Verbose Output -- **Invalid YAML:** Shows parsing error details -- **Missing Required Fields:** Indicates which fields are needed -- **Invalid Dates:** Warns about unrecognizable date formats +Control output verbosity globally via settings or per-calculation: + +**Global:** Settings → Date Calc → Verbose output + +**Per-calculation override:** -Example of invalid YAML: ```date-calc -this: is: not: valid +type: countdown +to: 2026-12-31 +verbose: true ``` -Example of missing field: -```date-calc -type: diff -from: 2025-01-01 -# Error: missing required "to" field +**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; +} ``` -## 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 +## Commands -## Troubleshooting Inline Code +- **Toggle debug** — Log decoration activity to console +- **Toggle verbose** — Switch global verbose mode -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